From 2ec2140ec83dcc6069e3e757641ca82809bc87eb Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 4 Sep 2024 18:11:28 -0500 Subject: [PATCH] PEP 735: expand "How to Teach This" (#3945) With the addition of `project.dependencies` includes from Dependency Groups, additions are warranted in the "How to Teach This" section of the PEP. Firstly, it is now useful to mention the similarity between a dependency group and an old-style `setup.py` which reads either as setup(install_requires=_read_helper("requirements.txt"), ...) or else as requirements = ["foo", ...] ... setup(install_requires=requirements, ...) Secondly, discussion of the interfaces for Dependency Groups adds a dimension to the document. For tool authors, this clarifies that allowing `project.dependencies` to use includes is necessary for build backends to declare support, but that there are no other formal requirements for tools. They will have to decide on interfaces -- and therefore what it means to support Dependency Groups -- for themselves. The spec provides only for the data. Additionally, the consequences for users, and the fact that this allows tools to define and enforce additional rules (which they must document) are called out explicitly. Implicitly, this hints that it is possible for tools to have conflicting requirements, so that it may become possible for toolA and toolB to have incompatible or at least orthogonal needs. Due to the relatively low risk of outright conflicts, and the ability of responsible tool maintainers to work through such cases if they do arise, this is not addressed at length. --- peps/pep-0735.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/peps/pep-0735.rst b/peps/pep-0735.rst index 4a133943e..bb1ee4c44 100644 --- a/peps/pep-0735.rst +++ b/peps/pep-0735.rst @@ -626,6 +626,12 @@ an include allows one Dependency Group to extend another. Similar configuration interfaces and the Python ``list.extend`` method may be used to explain the idea by analogy. +Python users who have used ``setup.py`` packaging may be familiar with common +practices which predate ``pyproject.toml``, in which package metadata is +defined dynamically. Requirements loaded from ``requirements.txt`` files and +definitions of static lists prior to ``setup()`` invocation readily analogize +with Dependency Groups. + Notes for Packages which are Repackaged --------------------------------------- @@ -642,6 +648,31 @@ updated. Ensure that repackaging consumers can contact you if there is an issue, and make sure to note transitions to use Dependency Groups in your changelogs. +Interfaces for Use of Dependency Groups +--------------------------------------- + +This specificaion provides no universal interface for interacting with +Dependency Groups, other than inclusion in a built package via the ``project`` +table. This has implications both for tool authors and for users. + +Tool authors should determine how or if Dependency Groups are relevant to their +user stories, and build their own interfaces to fit. +For environment managers, resolvers, installers, and related non-build tools, +they will be able to document that they support "PEP 735 Dependency Groups", +but they will be responsible for documenting their usage modes. +For build backends, supporting Dependency Groups will require support for +inclusion from the ``project`` table, but set no other strict requirements. + +For users, the primary consequence is that they must consult relevant tool +documentation whenever they wish to use Dependency Groups outside of package +builds. +Users should be advised by tools, either through documentation or runtime +warnings or errors, about usages which are disrecommended or not supported. +For example, if a tool wishes to require that all Dependency Groups are +mutually compatible, containing no contradictory package specifiers, it +should document that restriction and advise users on how to appropriately +leverage Dependency Groups for its purposes. + Rejected Ideas ==============