httk.core.docs.ecosystem¶

Discover and validate the module pins used by the aggregate documentation site.

Exceptions¶

Raised when an ecosystem checkout cannot produce a valid manifest.

`build_ecosystem_manifest`(submodules_dir, *[, ...])	Build the sorted manifest for direct Git checkouts under submodules_dir.
`read_ecosystem_manifest`(path)	Read a JSON manifest and report malformed files as typed errors.
`write_ecosystem_manifest`(manifest, output)	Write manifest as sorted, newline-terminated JSON using an atomic replace.
`verify_ecosystem_manifest`(submodules_dir, manifest_path, *)	Verify a committed manifest against the current checkout state.

exception httk.core.docs.ecosystem.EcosystemManifestError[source]¶

Raised when an ecosystem checkout cannot produce a valid manifest.

httk.core.docs.ecosystem.build_ecosystem_manifest(submodules_dir, *, require_release_tags=False)[source]¶

Build the sorted manifest for direct Git checkouts under submodules_dir.

Parameters:

submodules_dir (str | pathlib.Path) – Directory containing the expected direct checkouts.
require_release_tags (bool) – Require each checkout tag to match its distribution version.

Returns:

Manifest describing the checked-out modules.

Raises:

EcosystemManifestError – If checkout structure, Git state, or release metadata is invalid.

Return type:

dict[str, object]

httk.core.docs.ecosystem.read_ecosystem_manifest(path)[source]¶

Read a JSON manifest and report malformed files as typed errors.

Parameters:: path (str | pathlib.Path) – Manifest file to read.
Returns:: Validated ecosystem manifest.
Raises:: EcosystemManifestError – If the file cannot be read or has an invalid schema.
Return type:: dict[str, object]

httk.core.docs.ecosystem.write_ecosystem_manifest(manifest, output)[source]¶

Write manifest as sorted, newline-terminated JSON using an atomic replace.

Parameters:

manifest (collections.abc.Mapping[str, object]) – Ecosystem manifest to serialize.
output (str | pathlib.Path) – Destination manifest path.

Raises:

EcosystemManifestError – If the destination cannot safely be written.

httk.core.docs.ecosystem.verify_ecosystem_manifest(submodules_dir, manifest_path, *, require_release_tags=False)[source]¶

Verify a committed manifest against the current checkout state.

Parameters:

submodules_dir (str | pathlib.Path) – Directory containing the expected direct checkouts.
manifest_path (str | pathlib.Path) – Committed manifest to compare with the checkout state.
require_release_tags (bool) – Require each checkout tag to match its distribution version.

Raises:

EcosystemManifestError – If the checkout or manifest differs from the expected state.