Tweak rationale

python · brettcannon · Jul 24, 2024 · Mar 20, 2024 · Mar 21, 2024 · Mar 21, 2024
commit f4fc7284c521f2a981d0e65ec5396d78914e090b
diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst
@@ -70,22 +70,66 @@ section either already implement this approach of evaluating dependencies in
 isolation or have suggested they could in
 `Poetry's case <https://discuss.python.org/t/lock-files-again-but-this-time-w-sdists/46593/83>`__.
 
-The lock file format is designed to support two locking scenarios. The first is
-locking to specific files for an environment. This is to support workflows where
-the environment(s) are known ahead of time and specifying what exactly to
-install is important. This is similar to what ``pip freeze`` and pip-tools_
+
+Locking Scenarios
+-----------------
+
+The lock file format is designed to support two locking scenarios.
+
+
+Per-file Locking
+~~~~~~~~~~~~~~~~
+
+*Per-file locking* operates under the premise that one wants to install exact
+same files in matching environments. As such, the lock file specifies the
+requirements for an environment and then matches that environment requirements
+with the files to install. There can be multiple environments specified in a
+single file, each with their own set of files to install. By specifying the
+exact files to install avoids needs performing a resolution to decide what to
+install.
+
+The motivation for this approach to locking is for those who have controlled
+environments that they work with. For instance, if you have specific, controlled
+development and production environments then you can use per-file locking to
+make sure the **same** files are installed in either environment for everyone.
+
+This is similar to what ``pip freeze`` and pip-tools_
 support, but with more strictness of the exact files as well as incorporating
 into the file format the ability to specify the locked files for multiple
 environments.
 
-The second locking scenario is to lock to package versions. This is the approach
-taken by PDM_ (and indirectly by Poetry_). This is to support workflows where
-the environment(s) are not known ahead of time. This can happen in open source
-projects where contributors can have a myriad of different environments but
-there's a desire to lock the packages used for e.g. building the project's
-documentation. Since trying to lock the files for all possible environments
-could be tedious at best and very expensive at worst, locking to the package
-acts as a pragmatic compromise.
+
+Package Locking
+~~~~~~~~~~~~~~~
+
+*Package locking* lists the packages and their versions that *may* apply to any
+environment being installed for. The of packages and their version are evaluated
+individually and independently from any other packages and versions listed in
+the file. This allows installation to be linear -- read each package and version
+and make an isolated decision as to whether it should be installed -- and thus
+not require the installer to perform a resolution to decide what to install.
+
+The motivation of this approach comes from
+`PDM lock files <https://frostming.com/en/2024/pdm-lockfile/>`__. By listing the
+potential packages and versions that may be installed, what packages may be
+installed is controlled for in a way that's easy to reason about. This also
+allows for not specifying the exact environments that would be supported by the
+lock file so there's more flexibility and potentially easier
+-- and thus faster -- lock generation. This approach supports scenarios like
+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