|
| 1 | +Lock Files |
| 2 | +========== |
| 3 | + |
| 4 | +.. currentmodule:: packaging.pylock |
| 5 | + |
| 6 | +Parse and validate `pylock.toml files <https://packaging.python.org/en/latest/specifications/pylock-toml/>`_. |
| 7 | + |
| 8 | +Usage |
| 9 | +----- |
| 10 | + |
| 11 | +.. code-block:: python |
| 12 | +
|
| 13 | + import tomllib |
| 14 | + from pathlib import Path |
| 15 | +
|
| 16 | + from packaging.pylock import Package, PackageWheel, Pylock |
| 17 | + from packaging.utils import NormalizedName |
| 18 | + from packaging.version import Version |
| 19 | +
|
| 20 | + # validate a pylock file name |
| 21 | + assert is_valid_pylock_path(Path("pylock.example.toml")) |
| 22 | +
|
| 23 | + # parse and validate pylock file |
| 24 | + toml_dict = tomllib.loads(Path("pylock.toml").read_text(encoding="utf-8")) |
| 25 | + pylock = PyLock.from_dict(toml_dict) |
| 26 | + # the resulting pylock object is validated against the specification, |
| 27 | + # else a PylockValidationError is raised |
| 28 | +
|
| 29 | + # generate a pylock file |
| 30 | + pylock = Pylock( |
| 31 | + lock_version=Version("1.0"), |
| 32 | + created_by="some_tool", |
| 33 | + packages=[ |
| 34 | + Package( |
| 35 | + name=NormalizedName("example-package"), |
| 36 | + version=Version("1.0.0"), |
| 37 | + wheels=[ |
| 38 | + PackageWheel( |
| 39 | + url="https://example.com/example_package-1.0.0-py3-none-any.whl", |
| 40 | + hashes={"sha256": "0fd.."}, |
| 41 | + ) |
| 42 | + ], |
| 43 | + ) |
| 44 | + ], |
| 45 | + ) |
| 46 | + toml_dict = pylock.to_dict() |
| 47 | + # use a third-party library to serialize to TOML |
| 48 | +
|
| 49 | + # you can validate a manually constructed Pylock class |
| 50 | + pylock.validate() |
| 51 | +
|
| 52 | +Reference |
| 53 | +--------- |
| 54 | + |
| 55 | +.. autofunction:: is_valid_pylock_path |
| 56 | + |
| 57 | +The following frozen keyword-only dataclasses are used to represent the |
| 58 | +structure of a pylock file. The attributes correspond to the fields in the |
| 59 | +pylock file specification. |
| 60 | + |
| 61 | +.. autoclass:: Pylock |
| 62 | + :members: from_dict, to_dict, validate |
| 63 | + :exclude-members: __init__, __new__ |
| 64 | + |
| 65 | +.. class:: Package |
| 66 | + |
| 67 | +.. class:: PackageWheel |
| 68 | + |
| 69 | +.. class:: PackageSdist |
| 70 | + |
| 71 | +.. class:: PackageArchive |
| 72 | + |
| 73 | +.. class:: PackageVcs |
| 74 | + |
| 75 | +.. class:: PackageDirectory |
| 76 | + |
| 77 | +The following exception may be raised by this module: |
| 78 | + |
| 79 | +.. autoexception:: PylockValidationError |
| 80 | + :exclude-members: __init__, __new__ |
| 81 | + |
| 82 | +.. autoexception:: PylockUnsupportedVersionError |
| 83 | + :exclude-members: __init__, __new__ |
0 commit comments