Updates based on some review comments

- Drop core metadata 2.4 - Suggest SHA-256 or better - Suggest lockers set the simple Repo package URL - Rearrange the order of some keys
python · brettcannon · Jul 24, 2024 · Mar 20, 2024 · Mar 21, 2024 · Mar 21, 2024
commit 619bd6e0cc1f2f92f5494d9e891c041f3fa357e4
diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst
@@ -124,36 +124,13 @@ open source projects that want to lock what people should use to build the
 documentation as open source projects do not necessarily know upfront what
 environments their contributors are working from.
 
-One issue with this approach has with current packaging standards is that to be
-wholly accurate with what dependencies could be installed, every distribution
-file would need to be downloaded and analyzed. This is is not always practical
-if a `project has a lot of distribution files <https://pypi.org/project/charset-normalizer/#files>`__,
-especially when varying metadata between distribution files is considered rare.
-As such, this PEP includes a proposal of a new `core metadata`_ field to specify
-if metadata varies in any way between distribution files for a package version.
-
 As already mentioned, this approach is supported by PDM_. Poetry_ has
 `shown some interest <https://discuss.python.org/t/lock-files-again-but-this-time-w-sdists/46593/83>`__.
 
 
 Specification
 =============
 
-Core Metadata 2.4
------------------
-
-A new core metadata version of 2.4 is to be introduced. When metadata uses this
-version the contained metadata MUST be consistent across files for the same
-package and version unless it is marked as ``Dynamic``. This effectively means
-**all** wheel files will have the same metadata and source distributions _may_
-also have the same metadata **if** all the fields static (i.e. `Dynamic` is not
-set).
-
-This should allow for the reading of the metadata from any distribution file to
-know whether examining the other distribution files have the same or differing
 metadata.
-
-
 File Name
 ---------
 
@@ -312,6 +289,8 @@ other is disallowed.
 - String
 - Storess the `project detail`_ URL from the `Simple Repository API`_
 - Useful for generating Packaging URLs (aka *PURLs*)
+- When possible, lockers SHOULD include this key to assist with generating
+  `software bill of materials`_ (aka SBOMs)
 
 
 ``package.marker``
@@ -389,18 +368,16 @@ other is disallowed.
 - Necessary for installers to decide what to install when using package locking
 
 
-``package.files.hash``
+``package.files.lock``
 ''''''''''''''''''''''
 
-- String
-- The hash of the file contents
-- The format is ``f"{hashname}={hashvalue}"`` which is the same as the used by
-  the `Simple Repository API`_ and its HTML form
-- Only a single hash value is used to allow the table to be written inline
-- Using a single string to store both the hash algorithm and value instead of
-  separate keys for the two values is to make the inline table shorter
-- Used by installers to verify the file contents match what the locker worked
-  with
+- Required when ``[[file-lock]]`` is used
+- Array of strings
+- An array of ``file-lock.name`` values which signify that the file is to be
+  installed when the corresponding ``[[file-lock]]`` table applies to the
+  environment
+- There MUST only be a single file with any one ``file-lock.name`` entry per
+  package, regardless of version
 
 
 ``package.files.simple-repo-package-url``
@@ -413,6 +390,8 @@ other is disallowed.
   this file **only**
 - This is to support :pep:`708` when some files override what's provided by
   another `Simple Repository API`_ index
+- Lockers SHOULD include this key when appropriate to assist with generating
+  `software bill of materials`_ (aka SBOMs)
 
 
 ``package.files.origin``
@@ -425,16 +404,21 @@ other is disallowed.
   for the file if not already downloaded/available
 
 
-``package.files.lock``
+``package.files.hash``
 ''''''''''''''''''''''
 
-- Required when ``[[file-lock]]`` is used
-- Array of strings
-- An array of ``file-lock.name`` values which signify that the file is to be
-  installed when the corresponding ``[[file-lock]]`` table applies to the
-  environment
-- There MUST only be a single file with any one ``file-lock.name`` entry per
-  package, regardless of version
+- String
+- The hash of the file contents
+- The format is ``f"{hashname}={hashvalue}"`` which is the same as the used by
+  the `Simple Repository API`_ and its HTML form
+- Only a single hash value is used to allow the table to be written inline
+  for readability and compactness purposes
+- Using a single string to store both the hash algorithm and value instead of
+  separate keys for the two values is to make the inline table shorter
+- Used by installers to verify the file contents match what the locker worked
+  with
+- Lockers SHOULD use a hash algorithm that is as least as strong as
+  `SHA-256 <https://en.wikipedia.org/wiki/SHA-2>`__
 
 
 ``[package.vcs]``
@@ -527,9 +511,8 @@ other is disallowed.
 Expectations for Lockers
 ------------------------
 
-- When creating a lock file for ``[package-lock]`` and a package and version are
-  not using core metadata 2.4 as proposed by this PEP, the locker SHOULD read
-  the metadata of all files listed in ``[[package.files]]`` to make sure all
+- When creating a lock file for ``[package-lock]``, the locker SHOULD read
+  the metadata of **all** files listed in ``[[package.files]]`` to make sure all
   potential metadata cases are covered
 - If a locker chooses not to check every file for its metadata, the tool MUST
   either provide the user with the option to have all files checked (whether
@@ -670,5 +653,6 @@ _Poetry: https://python-poetry.org/
 _project detail: https://packaging.python.org/en/latest/specifications/simple-repository-api/#project-detail
 _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
 _version specifiers: https://packaging.python.org/en/latest/specifications/version-specifiers/
 _wheel tags: https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/