From ab07e44e92d471f4b8156946d5e091eedeabb5b5 Mon Sep 17 00:00:00 2001 From: Hugo Date: Fri, 10 Jul 2026 10:21:48 +0100 Subject: [PATCH 1/7] Document self-referential extras now that pip officially supports it Relevant PR: https://github.com/pypa/pip/pull/14157 Relevant Issue: https://github.com/pypa/pip/issues/11296 --- source/guides/writing-pyproject-toml.rst | 17 +++++++++++++++++ source/specifications/pyproject-toml.rst | 7 +++++++ 2 files changed, 24 insertions(+) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 92a7f25bf..6ce28553e 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -175,6 +175,22 @@ Each of the keys defines a "packaging extra". In the example above, one could use, e.g., ``pip install your-project-name[gui]`` to install your project with GUI support, adding the PyQt5 dependency. +.. _self-referential-extras: + +You can also define an extra that refers back to the same project with +other extras. This is useful for convenience extras that combine several +optional features without duplicating their dependency lists: + +.. code-block:: toml + + all = ["your-project-name[gui, cli]"] + +Installing ``your-project-name[all]`` then installs both the ``gui`` and +``cli`` dependencies. You can also list extras separately, for example +``["your-project-name[gui]", "your-project-name[cli]"]``. The name in the +requirement must match the project's ``name`` field. Installers such as +:ref:`pip` and :ref:`uv` support this pattern already (pip since v21.2). + .. _requires-python: .. _python_requires: @@ -555,6 +571,7 @@ A full example "rich", "click", ] + all = ["spam-eggs[gui, cli]"] [project.urls] Homepage = "https://example.com" diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index b4625bbb2..4b5a4a780 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -498,6 +498,13 @@ marker clause on the related ``Requires-Dist`` entries to check the extra name. Optional dependencies are thus only considered for installation if installation if the associated extra name is requested. +A dependency specifier in an extra MAY name the project itself with other extras +(for example, ``all = ["spam[gui, cli]"]``). That way a combined extra does not +need its own manually maintained copy of each referenced extra's dependencies, +which can otherwise fall out of sync. Installers that support self-referential +extras will be able to install the union of these extras' dependencies. See +:ref:`self-referential extras ` for examples. + .. _pyproject-toml-import-names: From d72cd8b978e469b562fc3390c25f9641c9688b00 Mon Sep 17 00:00:00 2001 From: Hugo Date: Fri, 10 Jul 2026 10:36:58 +0100 Subject: [PATCH 2/7] Update to include pip docs link --- source/guides/writing-pyproject-toml.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 6ce28553e..90fb7591c 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -189,7 +189,8 @@ Installing ``your-project-name[all]`` then installs both the ``gui`` and ``cli`` dependencies. You can also list extras separately, for example ``["your-project-name[gui]", "your-project-name[cli]"]``. The name in the requirement must match the project's ``name`` field. Installers such as -:ref:`pip` and :ref:`uv` support this pattern already (pip since v21.2). +:ref:`pip` and :ref:`uv` support this pattern already (pip since +`version 21.2 `_). .. _requires-python: From 68c3a77baafa24e65ce1bde8ea657001ccb03090 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 09:37:18 +0000 Subject: [PATCH 3/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- source/guides/writing-pyproject-toml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 90fb7591c..fa2760bab 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -189,7 +189,7 @@ Installing ``your-project-name[all]`` then installs both the ``gui`` and ``cli`` dependencies. You can also list extras separately, for example ``["your-project-name[gui]", "your-project-name[cli]"]``. The name in the requirement must match the project's ``name`` field. Installers such as -:ref:`pip` and :ref:`uv` support this pattern already (pip since +:ref:`pip` and :ref:`uv` support this pattern already (pip since `version 21.2 `_). From d45adcf5f81677fde743cffc2ee0c0d9f54c0221 Mon Sep 17 00:00:00 2001 From: Hugo Date: Sat, 11 Jul 2026 19:52:13 +0100 Subject: [PATCH 4/7] Rework the writing --- source/guides/writing-pyproject-toml.rst | 26 ++++++++++++++++-------- source/specifications/pyproject-toml.rst | 11 ++++------ 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index fa2760bab..665c1277b 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -177,20 +177,28 @@ project with GUI support, adding the PyQt5 dependency. .. _self-referential-extras: -You can also define an extra that refers back to the same project with +You can also define an extra that refers back to the current project with other extras. This is useful for convenience extras that combine several -optional features without duplicating their dependency lists: +optional features (such as an ``all`` extra hosting dependencies from both +``gui`` and ``cli``): .. code-block:: toml - all = ["your-project-name[gui, cli]"] + all = ["your-project-name[gui, cli]"] -Installing ``your-project-name[all]`` then installs both the ``gui`` and -``cli`` dependencies. You can also list extras separately, for example -``["your-project-name[gui]", "your-project-name[cli]"]``. The name in the -requirement must match the project's ``name`` field. Installers such as -:ref:`pip` and :ref:`uv` support this pattern already (pip since -`version 21.2 `_). +The combined extra does not need its own manually maintained copy of each +referenced extra's dependencies, which can otherwise fall out of sync after +a few years of maintenance and bug fixes: + +.. code-block:: toml + + gui = ["PyQt5"] + cli = [ + "rich>=14.2", # version range is added after last "all" extra update + "textual", # dependency newly added since last "all" extra update + "click", + ] + all = ["PyQt5", "rich", "click"] .. _requires-python: diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 4b5a4a780..7bc6ffbe1 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -498,13 +498,10 @@ marker clause on the related ``Requires-Dist`` entries to check the extra name. Optional dependencies are thus only considered for installation if installation if the associated extra name is requested. -A dependency specifier in an extra MAY name the project itself with other extras -(for example, ``all = ["spam[gui, cli]"]``). That way a combined extra does not -need its own manually maintained copy of each referenced extra's dependencies, -which can otherwise fall out of sync. Installers that support self-referential -extras will be able to install the union of these extras' dependencies. See -:ref:`self-referential extras ` for examples. - +Dependency specifiers in an extra may self-reference other extras from the +current project (e.g. ``all = ["your-project-name[gui, cli]"]``). See +:ref:`self-referential extras ` for an example. +Several installers including :ref:`pip` and :ref:`uv` support this pattern. .. _pyproject-toml-import-names: From c2eff8d9d436b25642cae6540922b51b7355f2cd Mon Sep 17 00:00:00 2001 From: Hugo Date: Wed, 5 Aug 2026 22:00:19 +0100 Subject: [PATCH 5/7] Update list of supported installer based on test results Tests are hosted in https://github.com/Trenza1ore/Self-Referential-Extras --- source/guides/writing-pyproject-toml.rst | 2 ++ source/specifications/pyproject-toml.rst | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 665c1277b..98601da8d 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -200,6 +200,8 @@ a few years of maintenance and bug fixes: ] all = ["PyQt5", "rich", "click"] +Most installers and dependency managers now support this kind of extra, including +:ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`. .. _requires-python: .. _python_requires: diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 7bc6ffbe1..c65e5494f 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -501,7 +501,8 @@ if the associated extra name is requested. Dependency specifiers in an extra may self-reference other extras from the current project (e.g. ``all = ["your-project-name[gui, cli]"]``). See :ref:`self-referential extras ` for an example. -Several installers including :ref:`pip` and :ref:`uv` support this pattern. +Most installers and dependency managers now support this kind of extra, including +:ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`. .. _pyproject-toml-import-names: From cd8e36378c3b959a17dec24486e84bb662c0a85e Mon Sep 17 00:00:00 2001 From: Hugo Date: Wed, 5 Aug 2026 23:46:19 +0100 Subject: [PATCH 6/7] Use the term "package managers" as it's most commonly used - "package installer" is only used to describe pip - "dependency manager" is only used to describe pipenv --- source/guides/writing-pyproject-toml.rst | 2 +- source/specifications/pyproject-toml.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 98601da8d..a0ff484f1 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -200,7 +200,7 @@ a few years of maintenance and bug fixes: ] all = ["PyQt5", "rich", "click"] -Most installers and dependency managers now support this kind of extra, including +Most package managers now support this kind of extra, including :ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`. .. _requires-python: diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index c65e5494f..d4e504317 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -501,7 +501,7 @@ if the associated extra name is requested. Dependency specifiers in an extra may self-reference other extras from the current project (e.g. ``all = ["your-project-name[gui, cli]"]``). See :ref:`self-referential extras ` for an example. -Most installers and dependency managers now support this kind of extra, including +Most package managers now support this kind of extra, including :ref:`pip`, :ref:`uv`, :ref:`poetry`, :ref:`hatch`, :ref:`pdm` and :ref:`pipenv`. .. _pyproject-toml-import-names: From 84ea0ced2c41efa884801ab873d00f3f3b73bf1d Mon Sep 17 00:00:00 2001 From: Hugo Date: Thu, 6 Aug 2026 14:18:56 +0100 Subject: [PATCH 7/7] Add history entry for this edit --- source/specifications/pyproject-toml.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index d4e504317..3fca99c9f 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -678,4 +678,7 @@ History - January 2026: Replaced outdated direct reference to :pep:`508` with a reference to :ref:`dependency-specifiers`. +- August 2026: Document self-referential extra as a supported feature by many + modern package managers of Python. + .. _TOML: https://toml.io