diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index 92a7f25bf..fa2760bab 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/source/guides/writing-pyproject-toml.rst @@ -175,6 +175,23 @@ 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 +`version 21.2 `_). + .. _requires-python: .. _python_requires: @@ -555,6 +572,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: