Skip to content

PEP 751: address feedback #4306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brettcannon merged 2 commits into from
Mar 17, 2025
Merged

PEP 751: address feedback #4306

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2275852
PEP 751: address feedback
brettcannon Mar 17, 2025
0395a5e
Address Sphinx errors
brettcannon Mar 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 107 additions & 23 deletions peps/pep-0751.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.

- **Type**: Array of strings
- **Required?**: no; defaults to ``[]``
- **Inspiration**: :ref:`packaging:pyproject-tool-table`
- **Inspiration**: :ref:`packaging:core-metadata-provides-extra`
- The list of :ref:`extras <packaging:core-metadata-provides-extra>` supported
by this lock file.
- Lockers MAY choose to not support writing lock files that support extras and
Expand Down Expand Up @@ -240,6 +240,22 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
is, in effect, multi-use even if it only looks to be single-use.


``default-group``
=================

- **Type**: String
- **Required?**: no
- **Inspiration**: Poetry_, PDM_
- The name of a synthetic dependency group to represent what should be installed
by default (e.g. what ``project.dependencies`` implicitly represents).
- Meant to be used in situations where ``packages.marker`` necessitates such a
group to exist.
- The group listed by this key SHOULD NOT be listed in ``dependency-groups`` as
the group is not meant to be directly exposed to users by name but instead via
an installer's UI.
- This group can only be specified when ``dependency-groups`` has values.


``created-by``
==============

Expand Down Expand Up @@ -455,7 +471,12 @@ consistent order. Usage of inline tables SHOULD also be kept consistent.
- **Type**: boolean
- **Required?**: no; defaults to ``false``
- **Inspiration**: :ref:`packaging:direct-url-data-structure-local-directory`
- A flag representing whether the source tree should be installed as editable.
- A flag representing whether the source tree was an editable install at lock
time.
- Installer MAY choose to ignore this flag if user actions or context would make
an editable install unnecessary or undesirable (e.g. a container image that
will not be mounted for development purposes but instead deployed to
production where it would be treated at read-only).


``packages.directory.subdirectory``
Expand Down Expand Up @@ -567,7 +588,8 @@ See ``packages.vcs.subdirectory``.
'''''''''''''''''''''''

- **Type**: string
- **Required?**: yes
- **Required?**: no, not when the last component of ``path``/ ``url`` would be
the same value
- **Inspiration**: PDM_, Poetry_, uv_
- The file name of the :ref:`packaging:source-distribution-format-sdist` file.

Expand Down Expand Up @@ -620,7 +642,8 @@ See ``packages.archive.hashes``.
''''''''''''''''''''''''

- **Type**: string
- **Required?**: yes
- **Required?**: no, not when the last component of ``path``/ ``url`` would be
the same value
- **Inspiration**: PDM_, Poetry_, uv_
- The file name of the :ref:`packaging:binary-distribution-format` file.

Expand Down Expand Up @@ -715,22 +738,69 @@ contexts where marker syntax is used (e.g. ``METADATA``, ``pyproject.toml``).

First, two new markers will be introduced: ``extras`` and
``dependency_groups``. They represent the extras and dependency groups that have
been requested to be installed, respectively.

Second, the marker specification will be changed to allow for containers and not
just strings for values. ONLY the new markers introduced in this PEP MAY and
MUST be used with a :py:class:`collections.abc.Container` type for their
value (which default to empty containers). An assumption of the type of
container used MUST NOT be made (e.g. could be a set, list, or tuple).
been requested to be installed, respectively:

.. code-block:: diff

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 06897da2..c9ab247f 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -87,7 +87,7 @@ environments::
'platform_system' | 'platform_version' |
'platform_machine' | 'platform_python_implementation' |
'implementation_name' | 'implementation_version' |
- 'extra' # ONLY when defined by a containing layer
+ 'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
)
marker_var = wsp* (env_var | python_str)
marker_expr = marker_var marker_op marker_var

This does NOT preclude using the same syntax parser in other contexts, only
where the new markers happen to be considered valid based on context.

Second, the marker specification will be changed to allow sets for values (on
top of the current support for strings and versions). ONLY the new markers
introduced in this PEP will allow for a set for their value (which defaults to
an empty set). This specifically does NOT update the spec to allow for set
literals.

Third, the marker expression syntax specification will be updated to allow for
operations involving sets:

.. code-block:: diff

diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 06897da2..ac29d796 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -196,15 +196,16 @@ safely evaluate it without running arbitrary code that could become a security
vulnerability. Markers were first standardised in :pep:`345`. This document
fixes some issues that were observed in the design described in :pep:`426`.

-Comparisons in marker expressions are typed by the comparison operator. The
-<marker_op> operators that are not in <version_cmp> perform the same as they
-do for strings in Python. The <version_cmp> operators use the version comparison
-rules of the :ref:`Version specifier specification <version-specifiers>`
-when those are defined (that is when both sides have a valid
-version specifier). If there is no defined behaviour of this specification
-and the operator exists in Python, then the operator falls back to
-the Python behaviour. Otherwise an error should be raised. e.g. the following
-will result in errors::
+Comparisons in marker expressions are typed by the comparison operator and the
+type of the marker value. The <marker_op> operators that are not in
+<version_cmp> perform the same as they do for strings or sets in Python based on
+whether the marker value is a string or set itself. The <version_cmp> operators
+use the version comparison rules of the
+:ref:`Version specifier specification <version-specifiers>` when those are
+defined (that is when both sides have a valid version specifier). If there is no
+defined behaviour of this specification and the operator exists in Python, then
+the operator falls back to the Python behaviour for the types involved.
+Otherwise an error should be raised. e.g. the following will result in errors::

"dog" ~= "fred"
python_version ~= "surprise"

Third, the "<marker_op> operators that are not in <version_cmp>" will be changed
from operating "the same as they do for *strings*" to "the same as they
do for *containers*". There are no backwards-compatibility concerns as strings
are containers themselves.

Fourth, a tool MUST raise an error if an extra or dependency group is specified
in a marker expression that does not exist in ``extras`` or
``dependency-groups``, respectively.

These changes, along with ``packages.extras``/ ``packages.dependency-groups``
and marker expressions' Boolean logic support, allow for expressing arbitrary,
Expand Down Expand Up @@ -806,10 +876,6 @@ Example
run-on = 2025-03-06T12:28:57.760769






------------
Installation
------------
Expand Down Expand Up @@ -923,6 +989,17 @@ file. Recording the sdist file name is for the same reason.

This PEP supports multi-use lock files while requirements files are single-use.

This PEP does NOT fully replace requirements files because:

- They support specifying installation
`options <https://pip.pypa.io/en/stable/reference/requirements-file-format/#supported-options>`__
at install-time (e.g. ``--index-url``, ``--constrants``).
- They can
`reference other requirements files <https://pip.pypa.io/en/stable/reference/requirements-file-format/#referring-to-other-requirements-files>`__
via ``-r``.
- They can
`use environment variables <https://pip.pypa.io/en/stable/reference/requirements-file-format/#using-environment-variables>`__ .


=======================
Backwards Compatibility
Expand Down Expand Up @@ -997,6 +1074,13 @@ lock files at least support single-use lock files. Neither type of lock file
is better or worse than the other, it just changes how much can be written down
in a single file (which can influence how manageable).

Lock files that follow this PEP can be installed by any installer that
implements the specification. This allows users of a lock file to not not be
tied to the locker used by the person who produced the lock file. But it is not
the case that using a different locker will lead to the same result. This could
be for various reasons, including using different algorithms to determine what
to lock.


========================
Reference Implementation
Expand Down