httk.core.building

Provide generalized build vocabulary and execution for httk manifests.

Attributes

DEFAULT_TAG

Exceptions

BuildError

Describe a build failure with its protocol code.

Classes

BuildSpec	Describe a build command and its disposable artifacts.
BuildResult	Describe the result of executing a build.

Functions

read_manifest_build_spec(root, *, manifest_name, ...)	Read and validate the optional build table in a manifest.
artifact_excluder(spec)	Return a predicate for declared artifacts and their descendants.
platform_tag(platform_command, *[, env])	Probe and tag the current platform.
execute_build(source, spec, *, strip_env_prefixes[, ...])	Execute a build and collect its declared artifacts.
write_generation(builds_root, relative, tag, source, ...)	Copy build artifacts into an atomically registered generation.
registered_generation(builds_root, relative, tag, *, ...)	Return registered artifacts when the build stamp still matches.
overlay_artifacts(artifacts_dir, target)	Copy registered artifact files over a staged tree.

Module Contents

httk.core.building.DEFAULT_TAG = 'any'

class httk.core.building.BuildSpec

Describe a build command and its disposable artifacts.

Parameters:

• command – Supply the build command.

• artifacts – Name artifact patterns to exclude from source publication.

• platform – Restrict the build to a platform, when supplied.

command: str

artifacts: tuple[str, Ellipsis]

platform: str | None = None

exception httk.core.building.BuildError(code, message)

Bases: ValueError

Describe a build failure with its protocol code.

Parameters:

• code (str) – Identify the build failure.

• message (str) – Describe the build failure.

code

message

class httk.core.building.BuildResult

Describe the result of executing a build.

Parameters:

• tag – Identify the platform registration tag.

• platform_output – Preserve the raw platform probe output.

• artifact_files – Name the collected artifact files as relative POSIX paths.

tag: str

platform_output: str

artifact_files: tuple[str, Ellipsis]

httk.core.building.read_manifest_build_spec(root, *, manifest_name, table_name, protected_names)

Read and validate the optional build table in a manifest.

Parameters:

• root (pathlib.Path) – Locate the manifest directory.

• manifest_name (str) – Name the manifest file.

• table_name (str) – Name the top-level manifest table.

• protected_names (collections.abc.Sequence[str]) – Name members artifact patterns must preserve.

Returns:

The build specification, or None when absent.

Raises:

ValueError – If the manifest or build table is malformed.

Return type:

BuildSpec | None

httk.core.building.artifact_excluder(spec)

Return a predicate for declared artifacts and their descendants.

Parameters:

spec (BuildSpec | None) – Supply the build specification, when present.

Returns:

A predicate accepting relative POSIX paths.

Return type:

collections.abc.Callable[[str], bool]

httk.core.building.platform_tag(platform_command, *, env=None)

Probe and tag the current platform.

Parameters:

• platform_command (str | None) – Supply the platform probe command, when present.

• env (collections.abc.Mapping[str, str] | None) – Supply the probe environment, or inherit the current environment.

Returns:

The sanitized tag and the probe’s raw standard output.

Raises:

BuildError – If the platform probe cannot be run successfully.

Return type:

tuple[str, str]

httk.core.building.execute_build(source, spec, *, strip_env_prefixes, keep_env=(), log_path=None, stdout_to_stderr=False)

Execute a build and collect its declared artifacts.

Parameters:

• source (pathlib.Path) – Run the build from this source directory.

• spec (BuildSpec) – Describe the build command and artifact patterns.

• strip_env_prefixes (collections.abc.Sequence[str]) – Remove environment variables with these prefixes.

• keep_env (collections.abc.Sequence[str]) – Preserve these variable names despite their prefixes.

• log_path (pathlib.Path | None) – Optionally write build metadata at this path.

• stdout_to_stderr (bool) – Route inherited build standard output to standard error.

Returns:

The platform tag, probe output, and collected artifact paths.

Raises:

BuildError – If probing, execution, or artifact collection fails.

Return type:

BuildResult

httk.core.building.write_generation(builds_root, relative, tag, source, artifact_files, stamp)

Copy build artifacts into an atomically registered generation.

Parameters:

• builds_root (pathlib.Path) – Locate the build registration store.

• relative (str) – Identify the source registration relative to the store.

• tag (str) – Identify the platform registration.

• source (pathlib.Path) – Locate the built source tree.

• artifact_files (collections.abc.Sequence[str]) – Name relative POSIX artifact files to copy.

• stamp (collections.abc.Mapping[str, object]) – Supply the build stamp fields.

Returns:

The new generation directory.

Return type:

pathlib.Path

httk.core.building.registered_generation(builds_root, relative, tag, *, format_name, expected_source_sha256)

Return registered artifacts when the build stamp still matches.

Parameters:

• builds_root (pathlib.Path) – Locate the build registration store.

• relative (str) – Identify the source registration relative to the store.

• tag (str) – Identify the platform registration.

• format_name (str) – Require this build stamp format name.

• expected_source_sha256 (str | None) – Require this source digest when supplied.

Returns:

The registered artifact directory, or None when unusable.

Return type:

pathlib.Path | None

httk.core.building.overlay_artifacts(artifacts_dir, target)

Copy registered artifact files over a staged tree.

Parameters:

• artifacts_dir (pathlib.Path) – Locate the registered artifact tree.

• target (pathlib.Path) – Locate the staged tree to overlay.