feat(cli): Support PEP 735 (Dependency Groups)

[finswimmer]

• Pin poetry-core to main after feat: Support PEP 735 dependency groups poetry-core#823 is merged.

Pull Request Check List

Requires: python-poetry/poetry-core#823
Resolves: #9751

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

Summary by Sourcery

Support PEP 735 by adding dependency groups to the pyproject.toml file.

New Features:

• Added support for dependency groups, as described in PEP 735.

Tests:

• Fixed failing tests due to dependency group changes.

Summary by Sourcery

Update dependency management to support PEP 735 (Dependency Groups).

New Features:

• Introduce dependency groups, allowing for more granular control over dependency management.

Tests:

• Fix failing tests due to dependency group changes.

Summary by Sourcery

Implement PEP 735 dependency-groups support across the CLI and project scaffolding while preserving backward compatibility with the existing tool.poetry.group format, update tests and documentation accordingly.

New Features:

• Add support for PEP 735 [dependency-groups] in the add and remove CLI commands
• Generate and preserve a dependency-groups section in init, layout, and self commands

Enhancements:

• Retain compatibility with legacy tool.poetry.group.* sections alongside PEP 735 groups
• Rename create_pyproject_from_package to create_legacy_pyproject_from_package and adjust factory accordingly

Build:

• Pin poetry-core dependency to the POC-PEP-735 branch after upstream merge

Documentation:

• Update managing-dependencies guide with PEP 735 examples and tabs for dual syntax

Tests:

• Parametrize and update add/remove/init/self tests to cover both PEP 735 and legacy group formats

[sourcery-ai]

Reviewer's Guide

Implement PEP 735 support by introducing a top-level dependency-groups section and extending CLI commands, project layout, self-commands, tests, and documentation to read/write both PEP 735 and legacy tool.poetry.group formats.

Entity Relationship diagram for dependency group sections in pyproject.toml

erDiagram
    PYPROJECT_TOML {
        string version
        string description
        string requires-python
        array dependencies
    }
    DEPENDENCY_GROUPS {
        array group_name
        array dependencies
    }
    TOOL_POETRY {
        array packages
    }
    TOOL_POETRY_GROUP {
        string group_name
        boolean optional
        array dependencies
    }
    PYPROJECT_TOML ||--|{ DEPENDENCY_GROUPS : "has"
    PYPROJECT_TOML ||--|{ TOOL_POETRY : "has"
    TOOL_POETRY ||--|{ TOOL_POETRY_GROUP : "has"
    DEPENDENCY_GROUPS ||--|{ TOOL_POETRY_GROUP : "legacy fallback"

Loading

Class diagram for updated add/remove command logic

classDiagram
    class AddCommand {
        +handle()
        -use_project_section: bool
        -use_groups_section: bool
        -groups_content
        -project_content
        -poetry_content
    }
    class RemoveCommand {
        +handle()
        -groups_content
        -poetry_groups_content
        -_remove_packages()
    }
    AddCommand --> "reads/writes" groups_content
    RemoveCommand --> "reads/writes" groups_content
    RemoveCommand --> "reads/writes" poetry_groups_content

Loading

File-Level Changes

Change	Details	Files
Add/remove commands support PEP 735 dependency-groups	Read and merge top-level dependency-groups with legacy sections Introduce use_groups_section flag and route additions to dependency-groups Delete empty groups in both dependency-groups and tool.poetry.group Refactor parameter handling for add/remove to unify PEP 735 logic	src/poetry/console/commands/add.py src/poetry/console/commands/remove.py
Project layout and factory emit legacy and PEP 735 groups	Introduce create_legacy_pyproject_from_package for system use Emit dependency-groups in layout.generate_project_content Remove legacy group tables when empty	src/poetry/factory.py src/poetry/layouts/layout.py
Preserve and manage dependency-groups in self-commands	Preserve dependency-groups in system pyproject generation Update get_self_command_dependencies to read PEP 735 arrays Adapt self add/remove plugin commands to use dependency-groups	src/poetry/console/commands/self/self_command.py tests/console/commands/self/utils.py tests/console/commands/self/test_add_plugins.py tests/console/commands/self/test_remove_plugins.py
Expand and update console command tests for PEP 735	Parametrize remove/add tests for pep_735 True/False Add new tests covering add/remove against dependency-groups Update init tests to assert PEP 735 syntax in interactive flows	tests/console/commands/test_remove.py tests/console/commands/test_add.py tests/console/commands/test_init.py
Update docs and configuration for PEP 735	Add PEP 735 tabbed examples in managing-dependencies.md Pin poetry-core to PoC branch in pyproject.toml	docs/managing-dependencies.md pyproject.toml

Possibly linked issues

• Support PEP 735 – Dependency Groups in pyproject.toml #9751: The PR implements native support for PEP 735 dependency groups in Poetry's CLI, project layout, and updates documentation.

---

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.

[finswimmer]

@sourcery-ai review

[github-actions]

Deploy preview for website ready!

✅ Preview
https://website-78bzkdfem-python-poetry.vercel.app

Built with commit b85f0a9.
This pull request is being automatically deployed with vercel-action

[radoering]

Some feedback:

• To satisfy the export tests, you can try to add poetry remove --lock poetry-core in

  poetry/.github/workflows/.tests-matrix.yaml

  Line 115 in 9af386a

  poetry add --lock --group dev ../poetry

• The support pep 735 commit is missing a test for remove and the tests in test_remove_plugins are still xfail. (If this is still on your todo list ignore the comment).

[finswimmer]

@sourcery-ai review

[sourcery-ai]

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

Overall Comments:

• The remove command does not fully support the new dependency-groups format yet, as evidenced by the xfailed tests. This should be implemented before merging.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟡 Testing: 2 issues found
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

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

• X
• Mastodon
• LinkedIn
• Facebook

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

[finswimmer]

@sourcery-ai review

[sourcery-ai]

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

Overall Comments:

• Extract the common dependency-group setup logic from tests into helper functions to reduce duplication in the if-else blocks.
• Refactor the repeated type casts and handling of groups_content to improve code readability and maintainability.

Here's what I looked at during the review

• 🟡 General issues: 2 issues found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

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

• X
• Mastodon
• LinkedIn
• Facebook

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

[sourcery-ai]

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

• The add/remove command handlers are now very lengthy with repeated PEP 735 branching—extract the core dependency-group logic into dedicated helper methods or classes to simplify and DRY up the code.
• There’s a lot of duplicated test setup for PEP 735 vs legacy behavior; consolidate that into fixtures or helper functions to reduce boilerplate and make the intent clearer.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- The add/remove command handlers are now very lengthy with repeated PEP 735 branching—extract the core dependency-group logic into dedicated helper methods or classes to simplify and DRY up the code.
- There’s a lot of duplicated test setup for PEP 735 vs legacy behavior; consolidate that into fixtures or helper functions to reduce boilerplate and make the intent clearer.

## Individual Comments

### Comment 1
<location> `tests/console/commands/self/test_add_plugins.py:27` </location>
<code_context>
 def assert_plugin_add_result(
     tester: CommandTester,
     expected: str,
</code_context>

<issue_to_address>
Test assertion helper updated for new dependency group format.

Please add a test case with multiple plugins to verify correct array handling.
</issue_to_address>

---

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

• X
• Mastodon
• LinkedIn
• Facebook

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

[radoering]

Looks quite good so far. I will do some exploratory testing later.

Just one small thing: I think we should add a test for poetry remove similar to test_remove_from_project_and_poetry for dependencies with additional information in the tool.poetry section.

[radoering]

@sourcery-ai review

[sourcery-ai]

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

• Extract the repeated pep_735 parameterization and assertion blocks in tests into shared fixtures or helper functions to reduce boilerplate and improve maintainability.
• Refactor the add/remove command handle() methods to encapsulate PEP 735 vs legacy group manipulation into helper utilities, reducing deep branching and improving readability.
• Unify or parameterize the two factory methods create_pyproject_from_package and create_legacy_pyproject_from_package to avoid duplicating similar pyproject generation logic.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Extract the repeated pep_735 parameterization and assertion blocks in tests into shared fixtures or helper functions to reduce boilerplate and improve maintainability.
- Refactor the add/remove command handle() methods to encapsulate PEP 735 vs legacy group manipulation into helper utilities, reducing deep branching and improving readability.
- Unify or parameterize the two factory methods create_pyproject_from_package and create_legacy_pyproject_from_package to avoid duplicating similar pyproject generation logic.

## Individual Comments

### Comment 1
<location> `tests/console/commands/test_add.py:671` </location>
<code_context>
+    ]
+
+
+def test_add_to_group_with_latest_overwrite_existing(
+    app: PoetryTestApplication, tester: CommandTester
+) -> None:
</code_context>

<issue_to_address>
Consider adding a test for adding a dependency with a lower version than the existing one.

Please add a test to confirm that adding a lower version does not unintentionally downgrade the dependency, unless this is the desired behavior.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
def test_add_to_group_with_latest_overwrite_existing(
    app: PoetryTestApplication, tester: CommandTester
) -> None:
=======
def test_add_to_group_with_latest_overwrite_existing(
    app: PoetryTestApplication, tester: CommandTester
) -> None:

def test_add_to_group_with_lower_version_does_not_downgrade(
    app: PoetryTestApplication, tester: CommandTester
) -> None:
    # Setup: Add a dependency with a higher version first
    tester.execute(
        "add cachy@^0.2.0 --group example",
        app=app,
    )
    # Try to add a lower version
    tester.execute(
        "add cachy@0.1.0 --group example",
        app=app,
    )
    pyproject = app.poetry.file.read()
    pyproject = cast("dict[str, Any]", pyproject)
    # Assert that the dependency is not downgraded
    assert "example" in pyproject["dependency-groups"]
    # The version should still be >=0.2.0,<0.3.0, not downgraded to 0.1.0
    assert any("cachy (>=0.2.0,<0.3.0)" in dep for dep in pyproject["dependency-groups"]["example"])
    assert not any("cachy (==0.1.0)" in dep for dep in pyproject["dependency-groups"]["example"])
>>>>>>> REPLACE

</suggested_fix>

### Comment 2
<location> `tests/console/commands/test_add.py:732` </location>
<code_context>
+    ]
+
+
+def test_add_to_group_uses_existing_legacy_group(
+    app: PoetryTestApplication, tester: CommandTester
+) -> None:
</code_context>

<issue_to_address>
Consider adding a test for conflicting dependency names between legacy and PEP 735 groups.

Please add a test to verify that updates target the correct group when a dependency name appears in both a legacy and a PEP 735 group.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
def test_add_to_group_uses_existing_legacy_group(
    app: PoetryTestApplication, tester: CommandTester
) -> None:
=======
def test_add_to_group_uses_existing_legacy_group(
    app: PoetryTestApplication, tester: CommandTester
) -> None:
    # existing test code...

def test_add_to_group_with_conflicting_dependency_names(
    app: PoetryTestApplication, tester: CommandTester
) -> None:
    """
    Test that updates target the correct group when a dependency name appears in both
    a legacy and a PEP 735 group.
    """
    # Setup: Add 'requests' to both a legacy group and a PEP 735 group
    pyproject = app.poetry.file.read()
    pyproject["dependency-groups"] = {
        "legacy": [
            "requests (>=2.20.0,<3.0.0)",
        ],
        "pep735": [
            "requests (>=2.25.0,<2.26.0)",
        ],
    }
    app.poetry.file.write(pyproject)

    # Add 'requests' to the 'pep735' group with a new constraint
    result = tester.execute(
        ["add", "requests@^2.25.1", "--group", "pep735"],
        app=app,
    )
    assert result == 0

    updated_pyproject = app.poetry.file.read()
    # Only the 'pep735' group should be updated
    assert updated_pyproject["dependency-groups"]["legacy"] == [
        "requests (>=2.20.0,<3.0.0)",
    ]
    assert updated_pyproject["dependency-groups"]["pep735"] == [
        "requests (^2.25.1)",
    ]
>>>>>>> REPLACE

</suggested_fix>

### Comment 3
<location> `tests/console/commands/test_add.py:1332` </location>
<code_context>


-def test_add_to_dev_section(app: PoetryTestApplication, tester: CommandTester) -> None:
+def test_add_to_dev_group(app: PoetryTestApplication, tester: CommandTester) -> None:
     tester.execute("cachy --dev")

</code_context>

<issue_to_address>
Consider adding a test for adding to a custom group with special characters in the name.

Test group names containing dots, dashes, or reserved TOML characters to verify proper escaping in pyproject.toml.
</issue_to_address>

### Comment 4
<location> `tests/console/commands/test_remove.py:210` </location>
<code_context>
+    assert expected_poetry_string in string_content
+
+
+@pytest.mark.parametrize("pep_735", [True, False])
 def test_remove_without_specific_group_removes_from_all_groups(
+    pep_735: bool,
     tester: CommandTester,
</code_context>

<issue_to_address>
Consider adding a test for removing a dependency that does not exist in any group.

This will verify that the CLI handles non-existent dependencies gracefully and prevents unintended modifications to pyproject.toml.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
    assert expected_pep735_string in string_content
    assert expected_poetry_string in string_content
=======
    assert expected_pep735_string in string_content
    assert expected_poetry_string in string_content


@pytest.mark.parametrize("pep_735", [True, False])
def test_remove_nonexistent_dependency_does_not_modify_pyproject(
    pep_735: bool,
    tester: CommandTester,
    app: PoetryTestApplication,
    repo: TestRepository,
    installed: Repository,
) -> None:
    # Setup: pyproject.toml with some dependencies
    repo.add_package(Package("foo", "2.0.0"))
    repo.add_package(Package("bar", "1.0.0"))

    pyproject_before = app.poetry.file.read()
    pyproject_before_str = app.poetry.file.as_string()

    # Try to remove a dependency that does not exist
    result = tester.execute(["remove", "nonexistent-package"])

    # Assert: CLI should report not found
    assert "nonexistent-package" in result.stdout.lower()
    assert "not found" in result.stdout.lower() or "does not exist" in result.stdout.lower()

    # Assert: pyproject.toml is unchanged
    pyproject_after_str = app.poetry.file.as_string()
    assert pyproject_before_str == pyproject_after_str
>>>>>>> REPLACE

</suggested_fix>

### Comment 5
<location> `tests/console/commands/self/utils.py:11` </location>
<code_context>


-def get_self_command_dependencies(locked: bool = True) -> TOMLTable:
+def get_self_command_dependencies(locked: bool = True) -> Array | None:
     from poetry.console.commands.self.self_command import SelfCommand
     from poetry.locations import CONFIG_DIR
</code_context>

<issue_to_address>
Consider adding a test for the case where no dependency-groups are present in the system pyproject.

This ensures the function correctly returns None without errors when dependency-groups are absent.
</issue_to_address>

### Comment 6
<location> `tests/test_factory.py:167` </location>
<code_context>
     poetry = Factory().create_poetry(fixture_dir(project))
     package = poetry.package

-    pyproject: dict[str, Any] = Factory.create_pyproject_from_package(package)
+    pyproject: dict[str, Any] = Factory.create_legacy_pyproject_from_package(package)

     result = pyproject["tool"]["poetry"]
</code_context>

<issue_to_address>
Consider adding a test for the new PEP 735 pyproject generation method.

Only the legacy method is currently tested. Please add a test for the PEP 735-compliant pyproject generation to ensure both formats are validated and to prevent future regressions.

Suggested implementation:

```python
    poetry = Factory().create_poetry(fixture_dir(project))
    package = poetry.package

    # Test legacy pyproject generation
    pyproject_legacy: dict[str, Any] = Factory.create_legacy_pyproject_from_package(package)
    result_legacy = pyproject_legacy["tool"]["poetry"]
    expected = poetry.pyproject.poetry_config
    assert result_legacy == expected

    # Test PEP 735-compliant pyproject generation
    pyproject_pep735: dict[str, Any] = Factory.create_pyproject_from_package(package)
    # Adjust the assertion below as needed to match the expected structure for PEP 735
    result_pep735 = pyproject_pep735["project"]
    # You may need to define the expected PEP 735 structure if it differs from legacy
    # For now, we check that the project name matches
    assert result_pep735["name"] == expected["name"]

```

If the expected structure for PEP 735 differs significantly from the legacy format, you should define a separate `expected_pep735` variable with the correct expected data for the PEP 735 format and adjust the assertion accordingly.
</issue_to_address>

---

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

• X
• Mastodon
• LinkedIn
• Facebook

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

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.