httk.core.docs.lockfile

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

LockError

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

Functions

compute_input_hash(pyproject_path)	Hash the documentation dependency inputs, independent of TOML formatting.
generate_lock(project_dir, output_path, *[, ...])	Generate a lock by invoking uv pip compile or an injected command.
check_lock(project_dir, lock_path)	Raise LockError if a lock is missing or stale for project_dir.
read_lock_pins(lock_path)	Read normalized distribution names and versions from a lock file.
filter_lock_pins(pins, *, drop)	Return pins excluding all httk-* names and the explicitly dropped names.
internal_pins(pins)	Return the normalized subset of pins belonging to internal httk distributions.

Module Contents

exception httk.core.docs.lockfile.LockError

Bases: RuntimeError

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

httk.core.docs.lockfile.compute_input_hash(pyproject_path)

Hash the documentation dependency inputs, independent of TOML formatting.

Parameters:

pyproject_path (str | pathlib.Path) – Project metadata file containing the dependency inputs.

Returns:

SHA-256 digest of the canonicalized lock inputs.

Raises:

LockError – If the project metadata or dependency inputs are invalid.

Return type:

str

httk.core.docs.lockfile.generate_lock(project_dir, output_path, *, command_prefix=None)

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

Parameters:

• project_dir (str | pathlib.Path) – Project directory containing pyproject.toml.

• output_path (str | pathlib.Path) – Lock path, relative to the project directory when relative.

• command_prefix (collections.abc.Sequence[str] | None) – Command to invoke instead of uv.

Raises:

LockError – If inputs are invalid, compilation fails, or the lock cannot be written.

httk.core.docs.lockfile.check_lock(project_dir, lock_path)

Raise LockError if a lock is missing or stale for project_dir.

Parameters:

• project_dir (str | pathlib.Path) – Project directory whose dependency inputs are checked.

• lock_path (str | pathlib.Path) – Lock path, relative to the project directory when relative.

Raises:

LockError – If the lock is missing, malformed, stale, or has invalid pins.

httk.core.docs.lockfile.read_lock_pins(lock_path)

Read normalized distribution names and versions from a lock file.

Parameters:

lock_path (str | pathlib.Path) – Lock file to read.

Returns:

Mapping of normalized distribution names to pinned versions.

Return type:

dict[str, str]

httk.core.docs.lockfile.filter_lock_pins(pins, *, drop)

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

Parameters:

• pins (collections.abc.Mapping[str, str]) – Distribution pins to normalize and filter.

• drop (collections.abc.Iterable[str]) – Additional distribution names to exclude.

Returns:

Filtered pins keyed by normalized distribution name.

Return type:

dict[str, str]

httk.core.docs.lockfile.internal_pins(pins)

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

Parameters:

pins (collections.abc.Mapping[str, str]) – Distribution pins to normalize and filter.

Returns:

Pins whose normalized names start with httk-.

Return type:

dict[str, str]