API reference

The public API exported by provium.

provium

__version__ = version('provium') module-attribute

__all__ = ['Artifact', 'ArtifactCatalog', 'ArtifactHeader', 'ArtifactLineage', 'ArtifactReader', 'ArtifactRecord', 'ArtifactReference', 'ArtifactRegistration', 'ArtifactWriter', 'ConfigCodec', 'ConfigurationSnapshot', 'ExecutionContext', 'DumpInfo', 'DumpResult', 'LoadResult', 'JsonValue', 'JsonArtifact', 'JsonArtifactReader', 'JsonArtifactWriter', 'Procedure', 'ProcedureExecutionRecord', 'ProcedureInstance', 'ProcedureRecord', 'Session', 'VerificationResult', '__version__', 'decode_header', 'dump_artifact', 'discover_catalogs', 'encode_header', 'current_execution', 'current_session', 'open_artifact', 'inspect_dump', 'load_artifact', 'reset_discovery', 'session', 'verify_dump'] module-attribute

JsonValue = JsonScalar | list[JsonValue] | dict[str, JsonValue]

Artifact

Bind a logical artifact type to its concrete reader and writer types.

dump(reader, destination) classmethod

Dump a reader into a custom portable representation.

load(source, writer) classmethod

Load a custom portable representation into a writer.

ArtifactCatalog

Map canonical identifiers and aliases to typed artifact definitions.

registrations property

Canonical registrations keyed by canonical identifier.

ArtifactRegistration dataclass

ArtifactHeader dataclass

The generic metadata required to locate and identify an artifact body.

JsonArtifact

Bases: Artifact[JsonArtifactReader, JsonArtifactWriter]

Artifact containing a dependency-free, generic JSON value.

JsonArtifactReader

Bases: ArtifactReader

Read one generic JSON value from an artifact body.

JsonArtifactWriter

Bases: ArtifactWriter

Write one generic JSON value using deterministic UTF-8 encoding.

ArtifactReader

Own metadata and bounded body access for a concrete artifact reader.

inspect()

Return a value describing the artifact body for human inspection.

DumpInfo dataclass

DumpResult dataclass

LoadResult dataclass

VerificationResult dataclass

ArtifactWriter

Own writable body access separately from final container completion.

ConfigCodec

Bases: Protocol

Encode and decode one procedure configuration type.

ConfigurationSnapshot dataclass

A JSON-compatible configuration value paired with its codec identity.

ExecutionContext dataclass

One single-use, logically scoped execution of a procedure.

Procedure dataclass

Immutable procedure identity and its optional configuration codec.

ProcedureInstance dataclass

A lazy, session-bound procedure setup with repeatable executions.

ArtifactLineage dataclass

Bases: _Serializable

A normalized, mergeable DAG of artifacts and their producing executions.

ArtifactRecord dataclass

Bases: _Serializable

An artifact together with its finalized content digest and producer.

ArtifactReference dataclass

Bases: _Serializable

The catalog type and persistent identity of an artifact.

ProcedureExecutionRecord dataclass

Bases: _Serializable

One execution and the artifact edges observed during it.

ProcedureRecord dataclass

Bases: _Serializable

An immutable description and optional configuration snapshot of a procedure.

Session dataclass

A nested scope for artifact resources and observed dependencies.

open_artifact(path, *, expected=None)

open_artifact(path: str | PathLike[str]) -> ArtifactReader

open_artifact(path: str | PathLike[str], *, expected: type[Artifact[ReaderT, WriterT]]) -> ReaderT

open_artifact(path: str | PathLike[str], *, expected: tuple[type[Artifact], ...]) -> ArtifactReader

Open an artifact whose concrete type will be discovered from its header.

discover_catalogs()

Load and combine installed catalogs, caching a successful discovery.

reset_discovery()

Clear cached discovery state, primarily for isolated tests.

decode_header(data)

Decode and validate a complete artifact header from bytes.

encode_header(header)

Encode a complete fixed prefix and its canonical metadata.

dump_artifact(source, destination, *, representation='auto', overwrite=False)

Dump an artifact into a portable directory package.

inspect_dump(source)

Return summary metadata for a dump package.

load_artifact(source, destination, *, mode='exact', representation='auto', overwrite=False)

Load a dump, preserving identity unless modified content is allowed.

verify_dump(source)

Verify the structure and file digests of a dump package.

current_execution()

Return the active Provium execution in this logical context.

current_session()