PEP 735: Minor updates and fixes (#3627)

- Minor corrections / typo fixes
- Use a ref role for `use_cases` link. As currently written, it
  renders incorrectly to a relative link to a `use_cases` page.
- Fix header style for Use Cases Appendix
- Add an explicit Compatibility section to Rationale

Future compatibility and designing the Dependency Groups data to be
extensible is a particular area of concern within the PEP. Although it
is addressed to some degree in the Specification, this small note in
the Rationale clarifies that compatibility with spec extensions is a

---------

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
This commit is contained in:
Stephen Rosen 2024-01-26 17:47:10 -06:00 committed by GitHub
parent 1eb29bbed0
commit 9d82dd1cd8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 25 additions and 11 deletions

View File

@ -154,7 +154,7 @@ Use Cases
---------
The following use cases are considered important targets for this PEP. They are
defined in greater detail in the `Use Cases Appendix <use_cases>`_.
defined in greater detail in the :ref:`Use Cases Appendix <use_cases>`.
* Web Applications deployed via a non-python-packaging build process
* Libraries with unpublished dev dependency groups
@ -195,6 +195,20 @@ further:
* installation of a Dependency Group does not imply installation of a package's
dependencies (or the package itself)
Future Compatibility & Invalid Data
-----------------------------------
Dependency Groups are intended to be extensible in future PEPs.
However, Dependency Groups should also be usable by multiple tools in a
single Python project.
With multiple tools using the same data, it is possible that one implements
a future PEP which extends Dependency Groups, while another does not.
To support users in this case, this PEP defines and recommends validation
behaviors in which tools only examine Dependency Groups which they are using.
This allows multiple tools, using different versions of Dependency Groups data,
to share a single table in ``pyproject.toml``.
Specification
=============
@ -1034,10 +1048,10 @@ Web Applications
A web application (e.g. a Django or Flask app) often does not need to build a
distribution, but bundles and ships its source to a deployment toolchain.
For example, a source code repository may define python packaging metadata as
For example, a source code repository may define Python packaging metadata as
well as containerization or other build pipeline metadata (``Dockerfile``,
etc).
The python application is built by copying the entire repository into a
The Python application is built by copying the entire repository into a
build context, installing dependencies, and bundling the result as a machine
image or container.
@ -1052,9 +1066,9 @@ without relying on packaging metadata, and without trying to express their
needs in packaging terms.
Libraries
'''''''''
---------
Libraries are python packages which build distributions (sdist and wheel) and
Libraries are Python packages which build distributions (sdist and wheel) and
publish them to PyPI.
For libraries, Dependency Groups represent an alternative to ``extras`` for
@ -1090,12 +1104,12 @@ install the appropriate Dependency Groups along with the library when needed,
as in the case of ``test``.
Data Science Projects
'''''''''''''''''''''
---------------------
Data Science Projects typically take the form of a logical collection of
scripts and utilities for processing and analyzing data, using a common
toolchain. Components may be defined in the Jupyter Notebook format (ipynb),
but rely on the same common core set of utlities.
but rely on the same common core set of utilities.
In such a project, there is no package to build or install. Therefore,
``pyproject.toml`` currently does not offer any solution for dependency
@ -1133,7 +1147,7 @@ scripts. Such combinations of data are left as a problem for tool authors to
solve, and perhaps eventually standardize.
Lockfile Generation
'''''''''''''''''''
-------------------
There are a number of tools which generate lockfiles in the Python ecosystem
today. PDM and Poetry each use their own lockfile formats, and pip-tools
@ -1174,7 +1188,7 @@ As two examples of how combinations might be locked:
solution, rather than a set or matrix of solutions.)
Environment Manager Inputs
''''''''''''''''''''''''''
--------------------------
A common usage in tox, Nox, and Hatch is to install a set of dependencies into
a testing environment.
@ -1217,9 +1231,9 @@ environment managers, the environment managers will need to support processing
Dependency Groups similarly to how they support inline dependency declaration.
IDE and Editor Use of Requirements Data
'''''''''''''''''''''''''''''''''''''''
---------------------------------------
IDE and Editor integrations may benefit from conventional or configurable name
IDE and editor integrations may benefit from conventional or configurable name
definitions for Dependency Groups which are used for integrations.
There are at least two known scenarios in which it is valuable for an editor or