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.
This commit is contained in:
Stephen Rosen 2024-09-04 18:11:28 -05:00 committed by GitHub
parent 4660531503
commit 2ec2140ec8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 31 additions and 0 deletions

View File

@ -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
==============