pylock: add documentation

Author: sbidoul

docs/index.rst

@@ -30,6 +30,7 @@ The ``packaging`` library uses calendar-based versioning (``YY.N``).
     requirements
     metadata
     tags
+    pylock
     utils
 
 .. toctree::

docs/pylock.rst

@@ -0,0 +1,83 @@
+Lock Files
+==========
+
+.. currentmodule:: packaging.pylock
+
+Parse and validate `pylock.toml files <https://packaging.python.org/en/latest/specifications/pylock-toml/>`_.
+
+Usage
+-----
+
+.. code-block:: python
+
+    import tomllib
+    from pathlib import Path
+
+    from packaging.pylock import Package, PackageWheel, Pylock
+    from packaging.utils import NormalizedName
+    from packaging.version import Version
+
+    # validate a pylock file name
+    assert is_valid_pylock_path(Path("pylock.example.toml"))
+
+    # parse and validate pylock file
+    toml_dict = tomllib.loads(Path("pylock.toml").read_text(encoding="utf-8"))
+    pylock = PyLock.from_dict(toml_dict)
+    # the resulting pylock object is validated against the specification,
+    # else a PylockValidationError is raised
+
+    # generate a pylock file
+    pylock = Pylock(
+        lock_version=Version("1.0"),
+        created_by="some_tool",
+        packages=[
+            Package(
+                name=NormalizedName("example-package"),
+                version=Version("1.0.0"),
+                wheels=[
+                    PackageWheel(
+                        url="https://example.com/example_package-1.0.0-py3-none-any.whl",
+                        hashes={"sha256": "0fd.."},
+                    )
+                ],
+            )
+        ],
+    )
+    toml_dict = pylock.to_dict()
+    # use a third-party library to serialize to TOML
+
+    # you can validate a manually constructed Pylock class
+    pylock.validate()
+
+Reference
+---------
+
+.. autofunction:: is_valid_pylock_path
+
+The following frozen keyword-only dataclasses are used to represent the
+structure of a pylock file. The attributes correspond to the fields in the
+pylock file specification.
+
+.. autoclass:: Pylock
+    :members: from_dict, to_dict, validate
+    :exclude-members: __init__, __new__
+
+.. class:: Package
+
+.. class:: PackageWheel
+
+.. class:: PackageSdist
+
+.. class:: PackageArchive
+
+.. class:: PackageVcs
+
+.. class:: PackageDirectory
+
+The following exception may be raised by this module:
+
+.. autoexception:: PylockValidationError
+    :exclude-members: __init__, __new__
+
+.. autoexception:: PylockUnsupportedVersionError
+    :exclude-members: __init__, __new__

src/packaging/pylock.py

@@ -56,6 +56,7 @@ def _from_dict(cls, d: Mapping[str, Any]) -> Self: ...
 
 
 def is_valid_pylock_path(path: Path) -> bool:
+    """Check if the given path is a valid pylock file path."""
     return path.name == "pylock.toml" or bool(_PYLOCK_FILE_NAME_RE.match(path.name))
 
 
@@ -233,6 +234,8 @@ def _validate_hashes(hashes: Mapping[str, Any]) -> Mapping[str, Any]:
 
 
 class PylockValidationError(Exception):
+    """Raised when when input data is not spec-compliant."""
+
     context: str | None = None
     message: str
 
@@ -266,7 +269,7 @@ def __init__(self, key: str) -> None:
 
 
 class PylockUnsupportedVersionError(PylockValidationError):
-    pass
+    """Raised when encountering an unsupported `lock_version`."""
 
 
 @dataclass(frozen=True, init=False)
@@ -549,6 +552,8 @@ def is_direct(self) -> bool:
 
 @dataclass(frozen=True, init=False)
 class Pylock:
+    """A class representing a pylock file."""
+
     lock_version: Version
     environments: Sequence[Marker] | None = None
     requires_python: SpecifierSet | None = None
@@ -608,11 +613,19 @@ def _from_dict(cls, d: Mapping[str, Any]) -> Self:
 
     @classmethod
     def from_dict(cls, d: Mapping[str, Any]) -> Self:
+        """Create and validate a Pylock instance from a TOML dictionary.
+
+        Raises :class:`PylockValidationError` if the input data is not
+        spec-compliant.
+        """
         return cls._from_dict(d)
 
     def to_dict(self) -> Mapping[str, Any]:
+        """Convert the Pylock instance to a TOML dictionary."""
         return dataclasses.asdict(self, dict_factory=_toml_dict_factory)
 
     def validate(self) -> None:
-        """Validate the Pylock instance against the specification."""
+        """Validate the Pylock instance against the specification.
+
+        Raises :class:`PylockValidationError` otherwise."""
         self.from_dict(self.to_dict())