Repository navigation
Document spec_string; accept stdin on validate - - #172
Conversation
Document in-memory validation with BaseParser(spec_string=...) and teach `prance validate -` to read a spec from stdin using Click's dash convention (Path allow_dash + get_text_stream). Co-authored-by: Cursor AI <ai@cursor.sh> Co-authored-by: Cursor Grok 4.5 <grok@x.ai>
Reviewer's GuideRefactors CLI parser construction to support validating specs from stdin using the dash convention, centralizes parser configuration, and documents the new behavior and existing spec_string API, with tests enforcing stdin usage rules. Sequence diagram for prance validate handling stdin dash inputsequenceDiagram
actor User
participant prance_cli_validate as validate
participant Click as click
participant Stdin as stdin
participant Parser as BaseParser_ResolvingParser
User->>prance_cli_validate: prance validate -
prance_cli_validate->>Click: click.Path(allow_dash=True)
prance_cli_validate->>prance_cli_validate: urls.count("-")
alt [stdin used more than once]
prance_cli_validate-->>User: click.UsageError("stdin (-) can only be used once.")
else [stdin combined with other urls]
prance_cli_validate-->>User: click.UsageError("stdin (-) cannot be combined...")
else [single "-" argument]
prance_cli_validate->>prance_cli_validate: __parser_for_stdin(resolve, backend, strict, encoding, allow_recursion)
prance_cli_validate->>Click: click.get_text_stream("stdin", encoding)
Click-->>Stdin: open text stream
Stdin-->>prance_cli_validate: stream.read() (spec_string)
prance_cli_validate->>prance_cli_validate: __make_parser(spec_string)
prance_cli_validate->>Parser: BaseParser_ResolvingParser(url=None, spec_string, **kwargs)
prance_cli_validate->>prance_cli_validate: __validate(parser, "-")
prance_cli_validate-->>User: validation result
end
User->>prance_cli_validate: prance validate path.yml
prance_cli_validate->>prance_cli_validate: __parser_for_url(url, resolve, backend, strict, encoding, allow_recursion)
prance_cli_validate->>prance_cli_validate: __make_parser(url)
prance_cli_validate->>Parser: BaseParser_ResolvingParser(url, spec_string=None, **kwargs)
prance_cli_validate->>prance_cli_validate: __validate(parser, formatted_url)
prance_cli_validate-->>User: validation result
File-Level Changes
Assessment against linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The new parser helpers (
__parser_kwargs/__make_parser) mix building kwargs with emitting CLI output; consider separating side-effectful logging from argument construction so the functions stay easier to reuse and reason about. - In
validate, the repeated unpacking ofctx.objwhen calling__parser_for_urland__parser_for_stdincould be simplified by passing a single options object or using a small helper to avoid duplicating the same argument list in multiple places.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new parser helpers (`__parser_kwargs`/`__make_parser`) mix building kwargs with emitting CLI output; consider separating side-effectful logging from argument construction so the functions stay easier to reuse and reason about.
- In `validate`, the repeated unpacking of `ctx.obj` when calling `__parser_for_url` and `__parser_for_stdin` could be simplified by passing a single options object or using a small helper to avoid duplicating the same argument list in multiple places.
## Individual Comments
### Comment 1
<location path="tests/test_cli.py" line_range="118-127" />
<code_context>
assert result.exit_code == 0
+@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
+def test_validate_from_stdin(runner):
+ from prance import cli
+
+ with open("tests/specs/petstore.yaml", encoding="utf-8") as f:
+ content = f.read()
+
+ result = runner.invoke(cli.validate, ["-"], input=content)
+ assert result.exit_code == 0
+ assert 'Processing "-" (stdin)...' in result.output
+ assert "Validates OK as Swagger/OpenAPI 2.0!" in result.output
+
+
+@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
+def test_validate_stdin_cannot_combine_with_paths(runner):
+ from prance import cli
+
+ result = runner.invoke(
+ cli.validate, ["-", "tests/specs/petstore.yaml"], input="openapi: 3.0.0\n"
+ )
+ assert result.exit_code == 2
+ assert "cannot be combined" in result.output
+
+
</code_context>
<issue_to_address>
**suggestion (testing):** Add a test for the case where stdin (`-`) is used more than once to cover the `urls.count("-") > 1` guard.
The new `urls.count("-") > 1` guard is only indirectly tested via mixing `-` with a path. Please add a test (e.g. `test_validate_stdin_cannot_be_used_twice`) that calls `cli.validate(['-', '-'])` and asserts `exit_code == 2` and that the "stdin (-) can only be used once." message appears, so this specific error path is covered and guarded against regressions.
Suggested implementation:
```python
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
def test_validate_from_stdin(runner):
from prance import cli
with open("tests/specs/petstore.yaml", encoding="utf-8") as f:
content = f.read()
result = runner.invoke(cli.validate, ["-"], input=content)
assert result.exit_code == 0
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
def test_validate_stdin_cannot_be_used_twice(runner):
from prance import cli
result = runner.invoke(cli.validate, ["-", "-"], input="openapi: 3.0.0\n")
assert result.exit_code == 2
assert "stdin (-) can only be used once." in result.output
```
None required, assuming the `validate` command already emits the "stdin (-) can only be used once." message when `urls.count("-") > 1`. If the message text differs, adjust the assertion string to match the actual output.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| @pytest.mark.skipif(none_of("click"), reason="Click does not exist") | ||
| def test_validate_from_stdin(runner): | ||
| from prance import cli | ||
|
|
||
| with open("tests/specs/petstore.yaml", encoding="utf-8") as f: | ||
| content = f.read() | ||
|
|
||
| result = runner.invoke(cli.validate, ["-"], input=content) | ||
| assert result.exit_code == 0 | ||
| assert 'Processing "-" (stdin)...' in result.output |
There was a problem hiding this comment.
suggestion (testing): Add a test for the case where stdin (-) is used more than once to cover the urls.count("-") > 1 guard.
The new urls.count("-") > 1 guard is only indirectly tested via mixing - with a path. Please add a test (e.g. test_validate_stdin_cannot_be_used_twice) that calls cli.validate(['-', '-']) and asserts exit_code == 2 and that the "stdin (-) can only be used once." message appears, so this specific error path is covered and guarded against regressions.
Suggested implementation:
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
def test_validate_from_stdin(runner):
from prance import cli
with open("tests/specs/petstore.yaml", encoding="utf-8") as f:
content = f.read()
result = runner.invoke(cli.validate, ["-"], input=content)
assert result.exit_code == 0
@pytest.mark.skipif(none_of("click"), reason="Click does not exist")
def test_validate_stdin_cannot_be_used_twice(runner):
from prance import cli
result = runner.invoke(cli.validate, ["-", "-"], input="openapi: 3.0.0\n")
assert result.exit_code == 2
assert "stdin (-) can only be used once." in result.outputNone required, assuming the validate command already emits the "stdin (-) can only be used once." message when urls.count("-") > 1. If the message text differs, adjust the assertion string to match the actual output.
There was a problem hiding this comment.
Pull request overview
This PR improves Prance’s validation UX by documenting the already-supported spec_string= Python API for in-memory specs and extending the prance validate CLI to accept - as “read spec from stdin”, aligning with Click’s dash-means-stdin convention.
Changes:
- Document
BaseParser(spec_string=...)usage inREADME.rst. - Add
prance validate -support by reading stdin and constructing a parser from the in-memory spec string. - Add CLI tests covering stdin success and rejecting stdin combined with file paths, plus a changelog entry.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
tests/test_cli.py |
Adds CLI tests for validating from stdin and rejecting invalid stdin/path combinations. |
README.rst |
Documents spec_string usage and the new prance validate - stdin convention. |
prance/cli.py |
Implements stdin handling for validate -, centralizes parser construction, and adds input-argument constraints. |
changelog.d/157.feature.rst |
Adds a changelog fragment for the new documentation and stdin CLI behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| click.echo('Processing "-" (stdin)...') | ||
| stream = click.get_text_stream("stdin", encoding=encoding) | ||
| spec_string = stream.read() | ||
| parser = __make_parser( |
| @pytest.mark.skipif(none_of("click"), reason="Click does not exist") | ||
| def test_validate_from_stdin(runner): | ||
| from prance import cli | ||
|
|
||
| with open("tests/specs/petstore.yaml", encoding="utf-8") as f: | ||
| content = f.read() | ||
|
|
||
| result = runner.invoke(cli.validate, ["-"], input=content) | ||
| assert result.exit_code == 0 | ||
| assert 'Processing "-" (stdin)...' in result.output | ||
| assert "Validates OK as Swagger/OpenAPI 2.0!" in result.output | ||
|
|
||
|
|
||
| @pytest.mark.skipif(none_of("click"), reason="Click does not exist") | ||
| def test_validate_stdin_cannot_combine_with_paths(runner): | ||
| from prance import cli | ||
|
|
||
| result = runner.invoke( | ||
| cli.validate, ["-", "tests/specs/petstore.yaml"], input="openapi: 3.0.0\n" | ||
| ) | ||
| assert result.exit_code == 2 | ||
| assert "cannot be combined" in result.output | ||
|
|
Summary
spec_string=for in-memory validation (already supported)prance validate -reads a spec from stdin via Click (Path(allow_dash=True)+get_text_stream("stdin"))-with other paths / using-more than onceCloses #157
Test plan
pytest tests/test_cli.py(includes stdin cases)echo '...' | prance validate -/prance validate - < file.ymlMade with Cursor
Summary by Sourcery
Enable stdin-based spec validation in the CLI, centralize parser construction for URL and in-memory specs, and document the
spec_stringAPI and new CLI usage while covering the behavior with tests.New Features:
prance validate -CLI conventionEnhancements:
Documentation:
spec_stringparameter and the CLI dash-means-stdin behavior in the changelogTests: