PEP 751: address comments (#3883)
* PEP 751: address comments * Add a comment as to why `packages.files.origin` was left out for numpy * Make it even more obvious that file lock names are arbitrary * Tweak a sentence
This commit is contained in:
Brett Cannon
GitHub
parent
448f383dc0
commit
43eb5fe0dc
|
|
@ -177,6 +177,15 @@ All keys listed below are required unless otherwise noted. If two keys are
|
|||
mutually exclusive to one another, then one of the keys is required while the
|
||||
other is disallowed.
|
||||
|
||||
Keys in tables -- including the top-level table -- SHOULD be emitted by
|
||||
lockers in the order they are listed in this PEP when applicable unless
|
||||
another sort order is specified to minimize noise in diffs. If the keys are not
|
||||
explicitly specified in this PEP, then the keys SHOULD be sorted by
|
||||
lexicographic order.
|
||||
|
||||
As well, lockers SHOULD sort arrays in lexicographic order
|
||||
unless otherwise specified for the same reason.
|
||||
|
||||
|
||||
``version``
|
||||
===========
|
||||
|
|
@ -185,6 +194,9 @@ other is disallowed.
|
|||
- The version of the lock file format.
|
||||
- This PEP specifies the initial version -- and only valid value until future
|
||||
updates to the standard change it -- as ``"1.0"``.
|
||||
- If an installer supports the major version but not the minor version, a tool
|
||||
SHOULD warn when an unknown key is seen.
|
||||
- If an installer doesn't support a major version, it MUST raise an error.
|
||||
|
||||
|
||||
``hash-algorithm``
|
||||
|
|
@ -247,8 +259,6 @@ other is disallowed.
|
|||
values for those markers.
|
||||
- Compatibility is defined by the environment's values matching what is in the
|
||||
table.
|
||||
- Lockers SHOULD sort the keys lexicographically to minimize changes when
|
||||
updating the file.
|
||||
|
||||
|
||||
``file-locks.wheel-tags``
|
||||
|
|
@ -263,8 +273,6 @@ other is disallowed.
|
|||
same environment by having one array being a strict subset of another
|
||||
``file-locks.wheel-tags`` entry in the same file's
|
||||
``[[file-locks]]`` tables.
|
||||
- Lockers SHOULD sort the keys lexicographically to minimize changes when
|
||||
updating the file.
|
||||
- Lockers MUST NOT include
|
||||
`compressed tag sets <https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#compressed-tag-sets>`__
|
||||
or duplicate tags for consistency across lockers and to simplify checking for
|
||||
|
|
@ -416,7 +424,8 @@ other is disallowed.
|
|||
``[[packages.files]]``
|
||||
----------------------
|
||||
|
||||
- Must be specified if ``[packages.vcs]`` is not
|
||||
- Must be specified if ``[packages.vcs]`` and ``packages.directory`` is not
|
||||
(although may be specified simultaneously with the other options).
|
||||
- Array of tables
|
||||
- Tables can be written inline.
|
||||
- Represents the files to potentially install for the package and version.
|
||||
|
|
@ -461,8 +470,10 @@ other is disallowed.
|
|||
- Optional
|
||||
- String
|
||||
- URI where the file was found when the lock file was generated.
|
||||
- Useful for documenting where the file came from and potentially where to look
|
||||
for the file if not already downloaded/available.
|
||||
- Useful for documenting where the file was originally found and potentially
|
||||
where to look for the file if not already downloaded/available.
|
||||
- Installers MUST NOT assume the URL will always work, but installers MAY use
|
||||
the URL if it happens to work.
|
||||
|
||||
|
||||
``packages.files.hash``
|
||||
|
|
@ -478,8 +489,8 @@ other is disallowed.
|
|||
``[packages.vcs]``
|
||||
------------------
|
||||
|
||||
- Must be specified if ``[[packages.files]]`` is not (although may be specified
|
||||
simultaneously with ``[[packages.files]]``).
|
||||
- Must be specified if ``[[packages.files]]`` and ``packages.directory`` is not
|
||||
(although may be specified simultaneously with the other options).
|
||||
- Table representing the version control system containing the package and
|
||||
version.
|
||||
|
||||
|
|
@ -526,7 +537,8 @@ other is disallowed.
|
|||
``packages.directory``
|
||||
----------------------
|
||||
|
||||
- Optional and only valid when ``[package-lock]`` is specified
|
||||
- Must be specified if ``[[packages.files]]`` and ``packages.vcs`` is not
|
||||
and doing per-package locking.
|
||||
- String
|
||||
- A local directory where a source tree for the package and version exists.
|
||||
- Not valid under ``[[file-locks]]`` as this PEP does not make an attempt to
|
||||
|
|
@ -577,6 +589,135 @@ other is disallowed.
|
|||
`pyproject.toml specification`_.
|
||||
|
||||
|
||||
--------
|
||||
Examples
|
||||
--------
|
||||
|
||||
Per-file locking
|
||||
================
|
||||
|
||||
.. code-block:: toml
|
||||
|
||||
version = '1.0'
|
||||
hash-algorithm = 'sha256'
|
||||
dependencies = ['cattrs', 'numpy']
|
||||
|
||||
[[file-locks]]
|
||||
name = 'CPython 3.12 on manylinux 2.17 x86-64'
|
||||
marker-values = {}
|
||||
wheel-tags = ['cp312-cp312-manylinux_2_17_x86_64', 'py3-none-any']
|
||||
|
||||
[[file-locks]]
|
||||
name = 'CPython 3.12 on Windows x64'
|
||||
marker-values = {}
|
||||
wheel-tags = ['cp312-cp312-win_amd64', 'py3-none-any']
|
||||
|
||||
[[packages]]
|
||||
name = 'attrs'
|
||||
version = '23.2.0'
|
||||
multiple-entries = false
|
||||
description = 'Classes Without Boilerplate'
|
||||
requires-python = '>=3.7'
|
||||
dependents = ['cattrs']
|
||||
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'}
|
||||
]
|
||||
|
||||
[[packages]]
|
||||
name = 'cattrs'
|
||||
version = '23.2.3'
|
||||
multiple-entries = false
|
||||
description = 'Composable complex class support for attrs and dataclasses.'
|
||||
requires-python = '>=3.8'
|
||||
dependents = []
|
||||
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'}
|
||||
]
|
||||
|
||||
[[packages]]
|
||||
name = 'numpy'
|
||||
version = '2.0.1'
|
||||
multiple-entries = false
|
||||
description = 'Fundamental package for array computing in Python'
|
||||
requires-python = '>=3.9'
|
||||
dependents = []
|
||||
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'}
|
||||
]
|
||||
|
||||
|
||||
Per-package locking
|
||||
===================
|
||||
|
||||
Some values for ``packages.files.origin`` left out to make creating this
|
||||
example more easily as it was done by hand.
|
||||
|
||||
.. code-block:: toml
|
||||
|
||||
version = '1.0'
|
||||
hash-algorithm = 'sha256'
|
||||
dependencies = ['cattrs', 'numpy']
|
||||
|
||||
[package-lock]
|
||||
requires-python = ">=3.9"
|
||||
|
||||
|
||||
[[packages]]
|
||||
name = 'attrs'
|
||||
version = '23.2.0'
|
||||
multiple-entries = false
|
||||
description = 'Classes Without Boilerplate'
|
||||
requires-python = '>=3.7'
|
||||
dependents = ['cattrs']
|
||||
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'}
|
||||
]
|
||||
|
||||
[[packages]]
|
||||
name = 'cattrs'
|
||||
version = '23.2.3'
|
||||
multiple-entries = false
|
||||
description = 'Composable complex class support for attrs and dataclasses.'
|
||||
requires-python = '>=3.8'
|
||||
dependents = []
|
||||
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'}
|
||||
]
|
||||
|
||||
[[packages]]
|
||||
name = 'numpy'
|
||||
version = '2.0.1'
|
||||
multiple-entries = false
|
||||
description = 'Fundamental package for array computing in Python'
|
||||
requires-python = '>=3.9'
|
||||
dependents = []
|
||||
dependencies = []
|
||||
direct = false
|
||||
files = [
|
||||
{name = "numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:6bf4e6f4a2a2e26655717a1983ef6324f2664d7011f6ef7482e8c0b3d51e82ac"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:5daab361be6ddeb299a918a7c0864fa8618af66019138263247af405018b04e1"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:529af13c5f4b7a932fb0e1911d3a75da204eff023ee5e0e79c1751564221a5c8"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-win32.whl", hash = "sha256:173a00b9995f73b79eb0191129f2455f1e34c203f559dd118636858cc452a1bf"},
|
||||
{name = "numpy-2.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171"},
|
||||
]
|
||||
|
||||
|
||||
------------------------
|
||||
Expectations for Lockers
|
||||
------------------------
|
||||
|
|
@ -622,7 +763,17 @@ Expectations for Installers
|
|||
Installing for per-file locking
|
||||
===============================
|
||||
|
||||
An example workflow is:
|
||||
- If no compatible environment is found an error MUST be raised.
|
||||
- If multiple environments are found to be compatible then an error MUST be
|
||||
raised.
|
||||
- If a ``[[packages.files]]`` contains multiple matching entries an error MUST
|
||||
be raised due to ambiguity for what is to be installed.
|
||||
- If multiple ``[[packages]]`` entries for the same package have matching files
|
||||
an error MUST be raised due to ambiguity for what is to be installed.
|
||||
|
||||
|
||||
Example workflow
|
||||
----------------
|
||||
|
||||
- Iterate through each ``[[file-locks]]`` table to find the one that applies to
|
||||
the environment being installed for.
|
||||
|
|
@ -652,7 +803,13 @@ An example workflow is:
|
|||
Installing for package locking
|
||||
==============================
|
||||
|
||||
An example workflow is:
|
||||
- Verify that the environment is compatible with
|
||||
``package-lock.requires-python``; if it isn't an error MUST be raised.
|
||||
- If no way to install a required package is found, an error MUST be raised.
|
||||
|
||||
|
||||
Example workflow
|
||||
----------------
|
||||
|
||||
- Verify that the environment is compatible with
|
||||
``package-lock.requires-python``; if it isn't an error MUST be raised.
|
||||
|
|
@ -665,6 +822,7 @@ An example workflow is:
|
|||
- Iterate through the files listed in ``[[packages.files]]``, looking for the
|
||||
"best" file to install.
|
||||
- If no file is found, check for ``[packages.vcs]``.
|
||||
- It no VCS is found, check for ``packages.directory``.
|
||||
- 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue