httk.core.docs.inventories

Read and validate Sphinx intersphinx v2 inventory headers.

Exceptions

InventoryError

Raised when an inventory cannot be fetched or has unexpected metadata.

Functions

read_inventory_header(path_or_bytes)

Return project and version from the plain-text inventory header.

fetch_inventory(url, dest, *[, expected_project, ...])

Fetch an inventory from HTTP(S) or file://, validate it, and save it.

Module Contents

exception httk.core.docs.inventories.InventoryError

Bases: RuntimeError

Raised when an inventory cannot be fetched or has unexpected metadata.

httk.core.docs.inventories.read_inventory_header(path_or_bytes)

Return project and version from the plain-text inventory header.

Parameters:

path_or_bytes (str | pathlib.Path | bytes) – Inventory file path or its contents.

Returns:

Project and version declared by the inventory.

Raises:

InventoryError – If the inventory does not have the expected header.

Return type:

tuple[str, str]

httk.core.docs.inventories.fetch_inventory(url, dest, *, expected_project=None, expected_version=None)

Fetch an inventory from HTTP(S) or file://, validate it, and save it.

Parameters:

  • url (str) – HTTP(S) or file:// URL of the inventory.

  • dest (str | pathlib.Path) – Destination path for the validated inventory.

  • expected_project (str | None) – Required project header, when supplied.

  • expected_version (str | None) – Required version header, when supplied.

Returns:

Project and version declared by the fetched inventory.

Raises:

InventoryError – If fetching, validation, or saving the inventory fails.

Return type:

tuple[str, str]