feature: poetry show json output format #10487

Aearsears · 2025-08-01T21:49:11Z

Pull Request Check List

Resolves: #10451

Adds a --output option to the poetry show command for text and json outputs.

poetry self show is not updated and there is some test duplication in test_show.py but this PR doesn't update them as I wanted to keep changes as contained as possible.

Duplicated test coverage:

test_show_non_dev_with_basic_installed_packages captured in test_show_basic_with_group_options --without test
test_show_with_group_only captured in test_show_basic_with_group_options --only {MAIN_GROUP}
test_show_with_optional_group captured in test_show_basic_with_group_options --with time

I will open another PR for the duplicated tests.

Added tests for changed code.
Updated documentation for changed code.

Summary by Sourcery

Implement an --output flag for poetry show that enables JSON output alongside the existing text format, add validation for invalid or conflicting options, serialize package data to JSON in appropriate code paths, update tests accordingly, and document the new flag.

New Features:

Add an --output option to the poetry show command to select between text and JSON output
Support JSON formatting for both single-package and multi-package show invocations

Enhancements:

Validate the output format and disallow combining JSON output with the --tree option
Serialize package information to JSON in both single and list display modes

Documentation:

Document the --output option in the CLI reference and note supported formats and constraints

Tests:

Extend existing show command tests to verify JSON output across all options and edge cases
Add tests for invalid output formats and tree/JSON incompatibility errors

Summary by Sourcery

Add an --output flag to the poetry show command to support JSON output alongside text, with validation for invalid formats and conflicting --tree usage

New Features:

Add --output option for the poetry show command to choose between text and JSON formats
Enable JSON output for both single-package and multi-package displays, including group filters, top-level, outdated, latest, and reverse-dependency views

Enhancements:

Validate the --output argument and emit errors for unsupported formats or invalid --tree combinations
Refactor the show command to handle JSON serialization early and streamline display logic

Documentation:

Document the new --output option in the CLI reference with supported formats and constraints

Tests:

Parameterize existing show tests to cover both text and JSON output across all modes
Add tests for invalid --output values and JSON/--tree incompatibility errors

sourcery-ai · 2025-08-01T21:49:17Z

Reviewer's Guide

This PR adds a new --output option to the poetry show command, defines and enforces supported formats, and extends the display routines to serialize package data as JSON for both single-package and list outputs. The changes include validation of invalid format values and incompatible flags, a JSON serialization branch in the command logic, comprehensive test refactoring to parameterize and verify both text and JSON outputs (including error cases), and an update to the CLI documentation.

Sequence diagram for poetry show command with --output option

sequenceDiagram
    actor User
    participant CLI as Poetry CLI
    participant ShowCmd as ShowCommand
    participant Output as OutputFormatter

    User->>CLI: poetry show [options]
    CLI->>ShowCmd: parse arguments
    ShowCmd->>ShowCmd: validate --output value
    alt Invalid --output
        ShowCmd->>CLI: print error and exit
    else --output=json and --tree
        ShowCmd->>CLI: print error and exit
    else --output=json
        ShowCmd->>Output: serialize package(s) to JSON
        Output-->>ShowCmd: JSON string
        ShowCmd->>CLI: print JSON output
    else --output=text
        ShowCmd->>Output: format package(s) as text
        Output-->>ShowCmd: text output
        ShowCmd->>CLI: print text output
    end

Class diagram for ShowCommand with --output option

classDiagram
    class ShowCommand {
        +name: str
        +description: str
        +options: list
        +handle() int
        +_display_single_package_information()
        +_display_packages_information()
    }
    ShowCommand o-- OutputFormatter
    class OutputFormatter {
        +serialize_to_json()
        +format_as_text()
    }

File-Level Changes

Change	Details	Files
Add and validate the --output CLI option	Introduce OUTPUT_FORMATS constant Declare `output` option on ShowCommand with default `text` Reject unsupported formats and disallow JSON + --tree in handle()	`src/poetry/console/commands/show.py`
Implement JSON serialization for single-package output	Branch on `output == 'json'` in single-package display Build a dict with name/version/description/dependencies/required_by Dump JSON and return early	`src/poetry/console/commands/show.py`
Implement JSON serialization for multi-package output	Branch on `output == 'json'` in list display Accumulate package dicts with status/version/latest/dependencies/description Dump JSON array and return early	`src/poetry/console/commands/show.py`
Refactor tests to cover text and JSON outputs	Add `output_format_parametrize` decorator to test suite Modify existing tests to assert JSON vs text based on format Introduce tests for invalid format and JSON+tree errors	`tests/console/commands/test_show.py`
Update CLI documentation for --output option	Document `--output` usage, default, supported formats, and tree constraint	`docs/cli.md`

Possibly linked issues

'poetry show' could output more easily machine-readable output #10451: The PR adds a --output json option to the poetry show command, fulfilling the issue's request for machine-readable output.

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

Aearsears · 2025-08-02T02:15:54Z

@sourcery-ai review

sourcery-ai

Hey @Aearsears - I've reviewed your changes - here's some feedback:

A lot of the JSON vs text test scaffolding is very repetitive—consider extracting a helper or fixture to DRY up the parameterized tests and assertions.
In show.py you import json inside multiple blocks; moving it to the module scope would remove duplicate imports and improve readability.
There’s a typo in the --tree error message ('the the text output'); you might want to correct it to something like 'can only be used with the text output.'

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- A lot of the JSON vs text test scaffolding is very repetitive—consider extracting a helper or fixture to DRY up the parameterized tests and assertions.
- In show.py you import `json` inside multiple blocks; moving it to the module scope would remove duplicate imports and improve readability.
- There’s a typo in the `--tree` error message ('the the text output'); you might want to correct it to something like 'can only be used with the text output.'

## Individual Comments

### Comment 1
<location> `src/poetry/console/commands/show.py:135` </location>
<code_context>
+
+            return 1
+
+        if self.option("output") != "text" and self.option("tree"):
+            self.line_error(
+                "<error>Error: --tree option can only be used the the text output.</error>"
</code_context>

<issue_to_address>
Typo in error message: 'the the text output'.

Please correct the error message to remove the duplicate 'the'.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
                "<error>Error: --tree option can only be used the the text output.</error>"
=======
                "<error>Error: --tree option can only be used with the text output.</error>"
>>>>>>> REPLACE

</suggested_fix>

### Comment 2
<location> `src/poetry/console/commands/show.py:397` </location>
<code_context>
+                if show_why:
+                    required_by = reverse_deps(locked, locked_repository)
+                    if required_by:
+                        content = ",".join(required_by.keys())
+                        package["required_by"] = content
+
</code_context>

<issue_to_address>
Joining required_by keys with ',' may be ambiguous if package names contain commas.

Consider outputting 'required_by' as a list rather than a comma-separated string to avoid ambiguity if package names include commas.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
                    if required_by:
                        content = ",".join(required_by.keys())
                        package["required_by"] = content
=======
                    if required_by:
                        package["required_by"] = list(required_by.keys())
>>>>>>> REPLACE

</suggested_fix>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

src/poetry/console/commands/show.py

sourcery-ai · 2025-08-02T02:17:04Z