From 809544b9f4a2ee3bf549eacc8954395dc78545a5 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Wed, 15 Jan 2025 17:10:11 -0800 Subject: [PATCH] PEP 751: update the post history --- peps/pep-0751.rst | 53 ++++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/peps/pep-0751.rst b/peps/pep-0751.rst index 4b19f2fd0b1..48f55b7b4e0 100644 --- a/peps/pep-0751.rst +++ b/peps/pep-0751.rst @@ -8,6 +8,7 @@ Created: 24-Jul-2024 Post-History: `25-Jul-2024 `__ `30-Oct-2024 `__ + `15-Jan-2025 `__ Replaces: 665 ======== @@ -52,7 +53,7 @@ cost/barrier. The closest the community has to a standard are pip's `requirements files`_ which all the aforementioned tools either use directly as their file format or -export to (i.e. ``requirements.txt``). Unfortunately the format is not a +export to (i.e. ``requirements.txt``). Unfortunately, the format is not a standard but is supported by convention. It's also designed very much for pip's needs, limiting its flexibility and ease of use (e.g., it's a bespoke file format). Lastly, it is not secure by default (e.g., file hash support is @@ -78,7 +79,7 @@ file. It should also lead to faster installs which are much more frequent than creating a lock file. The data in the file should be consumable by tools not written in Python. This -allows for e.g., clould hosting providers to write their own tool to perform +allows for e.g., cloud hosting providers to write their own tool to perform installations in their preferred programming language. The file format should promote good security defaults. As the format is not @@ -105,7 +106,7 @@ A lock file MUST be named :file:`pylock.toml` or match the regular expression lock files exist. The use of the ``.toml`` file extension is to make syntax highlighting in editors easier and to reinforce the fact that the file format is meant to be human-readable. The prefix and suffix of a named file MUST be -lowercase when possible for easy detection and removal, +lowercase when possible, for easy detection and removal, e.g.: .. code-block:: Python @@ -126,10 +127,10 @@ File Format The format of the file is TOML_. -Tools SHOULD write their lock files in a consistent way to minmize noise in diff -output. Keys in tables -- including the top-level table -- SHOULD be recorded in -a consistent order. As well, tools SHOULD sort arrays in consistent order. Usage -of inline tables SHOULD also be kept consistent. +Tools SHOULD write their lock files in a consistent way to minimize noise in +diff output. Keys in tables -- including the top-level table -- SHOULD be +recorded in a consistent order. As well, tools SHOULD sort arrays in consistent +order. Usage of inline tables SHOULD also be kept consistent. ``metadata-version`` @@ -165,7 +166,7 @@ of inline tables SHOULD also be kept consistent. - **Required?**: no - **Inspiration**: PDM_, Poetry_, uv_ - Specifies the :ref:`packaging:core-metadata-requires-python` for the minimum - Python version compatibile for any environment supported by the lock file + Python version compatible for any environment supported by the lock file (i.e. the minimum viable Python version for the lock file). @@ -638,12 +639,12 @@ a suggestion): satisfied. #. For each package listed in ``[[packages]]``: - #. If ``marker`` is specified, check if it is satisfied; it it isn't, + #. If ``marker`` is specified, check if it is satisfied; if it isn't, skip to the next package. #. If ``requires-python`` is specified, check if it is satisfied; an error MUST be raised if it isn't. #. Check that no other instance of the package has been slated to be - installed; an error about the ambiguity MUST be raied otherwise. + installed; an error about the ambiguity MUST be raised otherwise. #. Check that the source of the package is specified appropriately (i.e. there are not conflicting sources in the package entry); an error MUST be raised if any issues are found. @@ -912,12 +913,12 @@ Other keys A single hash algorithm for the whole file ========================================== -Earlier versions of this PEP proposed having a single hash algrorithm be +Earlier versions of this PEP proposed having a single hash algorithm be specified per file instead of any number of algorithms per file. The thinking was that by specifying a single algorithm it would help with auditing the file when a specific hash algorithm was mandated for use. -In the end there was some objection to this idea. Typically it centered around +In the end there was some objection to this idea. Typically, it centered around the cost of rehashing large wheel files (e.g., PyTorch). There was also concern about making hashing decisions upfront on the installer's behalf which they may disagree with. In the end it was deemed better to have flexibility and let @@ -958,7 +959,7 @@ 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 +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. @@ -1173,8 +1174,8 @@ detail as to differentiate from any other entry for the same package in the file (inspired by uv_). -Including index-hosted attestatons -================================== +Including index-hosted attestations +=================================== :ref:`packaging:index-hosted-attestations` specifies attestation details for files uploaded to a package index like PyPI. Including some of those details may @@ -1189,7 +1190,7 @@ JSON payload as a string, or re-specify some or all of the attestation spec. Expanding the feature set ------------------------- -This PEP is currenty oriented towards standardizing on something that can +This PEP is currently oriented towards standardizing on something that can replace a ``requirements.txt`` file that acts as a lock file (e.g., what `pip-tools`_ produces). But with an expansion of features, the file format may be able to replace the internal lock file format used by tools like PDM_ and @@ -1200,9 +1201,9 @@ for creating a lock file. Record the requirements for extras of a package =============================================== -A project with a ``pyprojec.toml`` file may define some extras which add +A project with a ``pyproject.toml`` file may define some extras which add dependencies to install. In the simple case this would just be a matter of -marking an antry in ``[[packages]]`` as only applying when a specific extra is +marking an entry in ``[[packages]]`` as only applying when a specific extra is requested. Unfortunately the simple case doesn't cover all cases. Consider the following example where the latest release of NumPy is 2.2.1 and @@ -1221,7 +1222,7 @@ own then NumPy 2.2.1 should be recorded in the lock file, but if extra-2 is specified (either on its own or in conjunction with extra-1), then NumPy 1.26.4 should be recorded. -There are two possible soluutions to this. +There are two possible solutions to this. A single version across all extras in a single lock file @@ -1234,7 +1235,7 @@ you won't be wondering what version of NumPy you will end up with based on what extras you select. But this does mean that if you want the version of NumPy to vary across extras -you will need to create separate lock files for the varyious NumPy versions you +you will need to create separate lock files for the various NumPy versions you want. While not technically an issue, it is ergonomically a bit annoying when this is necessary. But it's not known how frequently varying package versions which depend on which extra(s) are chosen occur, and when they do occur do people @@ -1246,11 +1247,11 @@ used for. This works thanks to extras being additive, and thus only contributing more packages. -Support boolean logic for extra selection +Support Boolean logic for extra selection ----------------------------------------- Another solution to this problem is specifying the conditions under -which a package version applies. This would mean supporting boolean logic +which a package version applies. This would mean supporting Boolean logic to fully express the conditions under which a package applies. But historically extras have not been expressed this way. The use of the @@ -1267,9 +1268,9 @@ versions apply. For this to work we would either need to expand the use of the ``extra`` clause so it can be used in ``packages.marker`` or have an ``extras`` key which -expresses a boolean expression for under which the package should be used. In +expresses a Boolean expression for under which the package should be used. In both situations the spec around ``extra`` would need to be expanded by this PEP --- or another PEP before this one is accepted -- to lay out how boolean +-- or another PEP before this one is accepted -- to lay out how Boolean expressions would work in this case. @@ -1277,8 +1278,8 @@ Record dependency groups ======================== Dependency groups have the same concerns as extras mentioned above along with -lacking any preexisting clause for use in dependency specifiers. And so -dependency groups have the added issue that to use boolean expressions would +lacking any pre-existing clause for use in dependency specifiers. And so +dependency groups have the added issue that to use Boolean expressions would require defining a new clause type.