From 9d82dd1cd831fceba8f725d3085c31b389cb100c Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Fri, 26 Jan 2024 17:47:10 -0600 Subject: [PATCH] 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> --- peps/pep-0735.rst | 36 +++++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/peps/pep-0735.rst b/peps/pep-0735.rst index 42258f947..b83b4c204 100644 --- a/peps/pep-0735.rst +++ b/peps/pep-0735.rst @@ -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 `_. +defined in greater detail in the :ref:`Use Cases Appendix `. * 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