PEP 751: updates based on user feedback (#3969)

Co-authored-by: Hugo van Kemenade <[email protected]>

Author: brettcannon

peps/pep-0751.rst

@@ -359,16 +359,16 @@ unless otherwise specified for the same reason.
   purpose.
 
 
-``packages.simple-repo-package-url``
+``packages.index-url``
 ------------------------------------
 
 - Optional (although mutually exclusive with
-  ``packages.files.simple-repo-package-url``)
+  ``packages.files.index-url``)
 - String
-- Stores the `project detail`_ URL from the `Simple Repository API`_.
+- Stores the `project index`_ URL from the `Simple Repository API`_.
 - Useful for generating Packaging URLs (aka PURLs).
 - When possible, lockers SHOULD include this or
-  ``packages.files.simple-repo-package-url`` to assist with generating
+  ``packages.files.index-url`` to assist with generating
   `software bill of materials`_ (aka SBOMs).
 
 
@@ -464,29 +464,38 @@ unless otherwise specified for the same reason.
   package, regardless of version.
 
 
-``packages.files.simple-repo-package-url``
+``packages.files.index-url``
 ''''''''''''''''''''''''''''''''''''''''''
 
 - Optional (although mutually exclusive with
-  ``packages.simple-repo-package-url``)
+  ``packages.index-url``)
 - String
-- The value has the same meaning as ``packages.simple-repo-package-url``.
+- The value has the same meaning as ``packages.index-url``.
 - This key is available per-file to support :pep:`708` when some files override
   what's provided by another `Simple Repository API`_ index.
 
 
-``packages.files.origin``
-'''''''''''''''''''''''''
+``packages.files.url``
+''''''''''''''''''''''
 
-- Optional
+- Optional (and mutually exclusive with ``packages.path``)
 - String
-- URI where the file was found when the lock file was generated.
-- If the URI is a relative file path, it is considered relative to the lock
-  file.
+- URL where the file was found when the lock file was generated.
 - Useful for documenting where the file was originally found and potentially
   where to look for the file if it is not already downloaded/available.
-- Installers MUST NOT assume the URI will always work, but installers MAY use
-  the URI if it happens to work.
+- Installers MUST NOT assume the URL will always work, but installers MAY use
+  the URL if it happens to work.
+
+
+``packages.path``
+'''''''''''''''''
+
+- Optional (and mutually exclusive with ``packages.path``)
+- String
+- File system path to where the file was found when the lock file was generated.
+- Path may be relative to the lock file's location or absolute.
+- Installers MUST NOT assume the path will always work, but installers MAY use
+  the path if it happens to work.
 
 
 ``packages.files.hash``
@@ -518,11 +527,22 @@ unless otherwise specified for the same reason.
   of the direct URL data structure.
 
 
-``packages.vcs.origin``
+``packages.vcs.url``
 '''''''''''''''''''''''
 
+- Mutually exclusive with ``packages.vcs.path``
 - String
-- The URI of where the repository was located when the lock file was generated.
+- The URL of where the repository was located when the lock file was generated.
+
+
+``packages.vcs.path``
+'''''''''''''''''''''
+
+- Mutually exclusive with ``packages.vcs.url``
+- String
+- The file system path where the repository was located when the lock file was
+  generated.
+- The path may be relative to the lock file or absolute.
 
 
 ``packages.vcs.commit``
@@ -573,27 +593,6 @@ unless otherwise specified for the same reason.
   install.
 
 
-``[[packages.build-requires]]``
--------------------------------
-
-- Optional
-- An array of tables whose structure matches that of ``[[packages]]``.
-- Each entry represents a package and version to use when building the
-  enclosing package and version.
-- The array is complete/locked like ``[[packages]]`` itself (i.e. installers
-  follow the same installation procedure for ``[[packages.build-requires]]`` as
-  ``[[packages]]``)
-- Selection of which entries to use for an environment as the same as
-  ``[[packages]]`` itself, albeit only applying when installing the build
-  back-end and its dependencies.
-- This helps with reproducibility of the building of a package by recording
-  either what was or would have been used if the locker needed to build the
-  packages.
-- If the installer and user choose to install from source and this array is
-  missing then the installer MAY choose to resolve what to install for building
-  at install time, otherwise the installer MUST raise an error.
-
-
 ``[packages.tool]``
 -------------------
 
@@ -649,7 +648,7 @@ Per-file locking
   dependencies = []
   direct = false
   files = [
-      {name = 'attrs-23.2.0-py3-none-any.whl', lock = ['CPython 3.12 on manylinux 2.17 x86-64', 'CPython 3.12 on Windows x64'], origin = 'https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl', hash = '99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1'}
+      {name = 'attrs-23.2.0-py3-none-any.whl', lock = ['CPython 3.12 on manylinux 2.17 x86-64', 'CPython 3.12 on Windows x64'], url = 'https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl', hash = '99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1'}
   ]
 
   [[packages]]
@@ -662,7 +661,7 @@ Per-file locking
   dependencies = ['attrs']
   direct = false
   files = [
-      {name = 'cattrs-23.2.3-py3-none-any.whl', lock = ['CPython 3.12 on manylinux 2.17 x86-64', 'CPython 3.12 on Windows x64'], origin = 'https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl', hash = '0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108'}
+      {name = 'cattrs-23.2.3-py3-none-any.whl', lock = ['CPython 3.12 on manylinux 2.17 x86-64', 'CPython 3.12 on Windows x64'], url = 'https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl', hash = '0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108'}
   ]
 
   [[packages]]
@@ -675,15 +674,15 @@ Per-file locking
   dependencies = []
   direct = false
   files = [
-      {name = 'numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', lock = ['cp312-manylinux_2_17_x86_64'], origin = 'https://files.pythonhosted.org/packages/2c/f3/61eeef119beb37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', hash = '6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a'},
-      {name = 'numpy-2.0.1-cp312-cp312-win_amd64.whl', lock = ['cp312-win_amd64'], origin = 'https://files.pythonhosted.org/packages/b5/59/f6ad30785a6578ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl', hash = 'bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171'}
+      {name = 'numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', lock = ['cp312-manylinux_2_17_x86_64'], url = 'https://files.pythonhosted.org/packages/2c/f3/61eeef119beb37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', hash = '6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a'},
+      {name = 'numpy-2.0.1-cp312-cp312-win_amd64.whl', lock = ['cp312-win_amd64'], url = 'https://files.pythonhosted.org/packages/b5/59/f6ad30785a6578ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl', hash = 'bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171'}
   ]
 
 
 Per-package locking
 ===================
 
-Some values for ``packages.files.origin`` left out to make creating this
+Some values for ``packages.files.url`` left out to make creating this
 example more easily as it was done by hand.
 
 .. code-block:: toml
@@ -706,7 +705,7 @@ example more easily as it was done by hand.
   dependencies = []
   direct = false
   files = [
-      {name = 'attrs-23.2.0-py3-none-any.whl', lock = ['cp312-manylinux_2_17_x86_64', 'cp312-win_amd64'], origin = 'https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl', hash = '99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1'}
+      {name = 'attrs-23.2.0-py3-none-any.whl', lock = ['cp312-manylinux_2_17_x86_64', 'cp312-win_amd64'], url = 'https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl', hash = '99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1'}
   ]
 
   [[packages]]
@@ -719,7 +718,7 @@ example more easily as it was done by hand.
   dependencies = ['attrs']
   direct = false
   files = [
-      {name = 'cattrs-23.2.3-py3-none-any.whl', lock = ['cp312-manylinux_2_17_x86_64', 'cp312-win_amd64'], origin = 'https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl', hash = '0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108'}
+      {name = 'cattrs-23.2.3-py3-none-any.whl', lock = ['cp312-manylinux_2_17_x86_64', 'cp312-win_amd64'], url = 'https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl', hash = '0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108'}
   ]
 
   [[packages]]
@@ -821,9 +820,6 @@ Example workflow
   an error MUST be raised due to ambiguity for what is to be installed.
 - Find and verify the candidate files and/or VCS entries based on their hash or
   commit ID as appropriate.
-- If a source distribution or VCS was selected and
-  ``[[packages.build-requires]]`` exists, then repeat the above process as
-  appropriate to install the build dependencies necessary to build the package.
 - Install the candidate files.
 
 
@@ -853,9 +849,6 @@ Example workflow
 - If no match is found, an error MUST be raised.
 - Find and verify the selected files and/or VCS entries based on their hash or
   commit ID as appropriate.
-- If the match is a source distribution or VCS and
-  ``[[packages.build-requires]]`` is provided, repeat the above as appropriate
-  to build the package.
 - Install the selected files.
 
 
@@ -1096,6 +1089,16 @@ for was considered. In the end, though, it was rejected as it was deemed
 unnecessary bookkeeping.
 
 
+Locking build requirements for sdists
+=====================================
+
+An earlier version of this PEP tried to lock the build requirements for sdists
+under a ``packages.build-requires`` key. Unfortunately it confused enough people
+about how it was expected to operate and there were enough edge case issues to
+decide it wasn't worth trying to do in this PEP upfront. Instead, a future PEP
+could propose a solution.
+
+
 ===========
 Open Issues
 ===========
@@ -1133,7 +1136,7 @@ CC0-1.0-Universal license, whichever is more permissive.
 .. _PDM: https://pypi.org/project/pdm/
 .. _pip-tools: https://pypi.org/project/pip-tools/
 .. _Poetry: https://python-poetry.org/
-.. _project detail: https://packaging.python.org/en/latest/specifications/simple-repository-api/#project-detail
+.. _project index: https://packaging.python.org/en/latest/specifications/simple-repository-api/#project-list
 .. _pyproject.toml specification: https://packaging.python.org/en/latest/specifications/pyproject-toml/#pyproject-toml-specification
 .. _Simple Repository API: https://packaging.python.org/en/latest/specifications/simple-repository-api/
 .. _software bill of materials: https://www.cisa.gov/sbom