httk.core.docs.lockfile
=======================

.. py:module:: httk.core.docs.lockfile

.. autoapi-nested-parse::

   Portable documentation lock files and injectable ``uv pip compile`` tooling.

   The lock keeps four contract headers: schema, a canonical-input SHA-256 hash,
   Python 3.12, and Linux.  The resolver's comment noise is discarded; only
   ``name==version`` pins are retained after the headers.  Its pins cover runtime,
   documentation, and build-backend requirements so a clean Python 3.12
   environment can install the lock before using ``--no-build-isolation``.



Exceptions
----------

.. autoapisummary::

   httk.core.docs.lockfile.LockError


Functions
---------

.. autoapisummary::

   httk.core.docs.lockfile.compute_input_hash
   httk.core.docs.lockfile.generate_lock
   httk.core.docs.lockfile.check_lock
   httk.core.docs.lockfile.read_lock_pins
   httk.core.docs.lockfile.filter_lock_pins
   httk.core.docs.lockfile.internal_pins


Module Contents
---------------

.. py:exception:: LockError

   Bases: :py:obj:`RuntimeError`


   Raised when a documentation lock is absent, stale, or cannot be made.


.. py:function:: compute_input_hash(pyproject_path: str | pathlib.Path) -> str

   Hash the documentation dependency inputs, independent of TOML formatting.


.. py:function:: generate_lock(project_dir: str | pathlib.Path, output_path: str | pathlib.Path, *, command_prefix: collections.abc.Sequence[str] | None = None) -> None

   Generate a lock by invoking ``uv pip compile`` or an injected command.


.. py:function:: check_lock(project_dir: str | pathlib.Path, lock_path: str | pathlib.Path) -> None

   Raise :class:`LockError` if a lock is missing or stale for *project_dir*.


.. py:function:: read_lock_pins(lock_path: str | pathlib.Path) -> dict[str, str]

   Read normalized distribution names and versions from a lock file.


.. py:function:: filter_lock_pins(pins: collections.abc.Mapping[str, str], *, drop: collections.abc.Iterable[str]) -> dict[str, str]

   Return pins excluding all ``httk-*`` names and the explicitly dropped names.


.. py:function:: internal_pins(pins: collections.abc.Mapping[str, str]) -> dict[str, str]

   Return the normalized subset of pins belonging to internal httk distributions.