makeprov.prov

Functions

`apply_context`(node, context)	Bind a document-level context to a node and rebuild its term aliases.
`dataclass`([cls, init, repr, eq, order, ...])	Add dunder methods based on the fields defined in the class.
`deepcopy`(x[, memo, _nil])	Deep copy operation on arbitrary Python objects.
`field`(*[, default, default_factory, init, ...])	Return an object to identify dataclass fields.
`load_forges`([extra])	Load the built-in profiles, preceded by any user-supplied ones.
`pep503_normalize`(name)	Normalize a package name according to PEP 503 rules.
`project_metadata`([dist_name])	Extract package metadata for provenance enrichment.
`quote`()	Each part of a URL, e.g. the path info, the query, etc., has a different set of reserved characters that must be quoted.
`resolve_forge`(origin[, profiles])	Match a git remote against the known forges.
`resolve_iris`(base_iri, context, *[, ...])	Decide how a document's identifiers are minted.
`working_tree_is_dirty`()	Whether the checkout has uncommitted changes.

Classes

`ActivityNode`(id, type[, startedAtTime, ...])
`AgentNode`(id, type[, label, hasVersion, ...])
`Any`(args, *kwargs)	Special type indicating an unconstrained type.
`ArtifactRef`([id, path, types, digest, ...])	A reference to an entity a run consumed or produced.
`AssociationNode`(id, type[, agent, hadPlan])
`BaseNode`(id, type)
`DepNode`(id, type[, label])
`EnvNode`(id, type[, label, title, ...])
`FileEntity`(id, type[, format, extent, ...])
`GraphEntity`(id, type[, wasGeneratedBy, ...])
`IriMinter`(base_iri, prefix, pinned[, ...])	Mints the identifiers for one provenance document.
`Path`(args, *kwargs)	PurePath subclass that can make system calls.
`PersonNode`(id, type[, name, email])
`PlanGraph`(rule[, requires])	Prospective structure for one rule: its name and the rules it needs.
`PlanNode`(id, type[, label, hasVersion, ...])	The recipe an activity carried out, distinct from whoever ran it.
`Prov`(base_iri, name, provenance, results[, ...])
`ProvDoc`([provenance])
`RDFMixin`()	Provide JSON-LD serialization helpers for dataclasses.
`datetime`(year, month, day[, hour[, minute[, ...)	The year, month and day arguments are required.
`timezone`	Fixed offset from UTC implementation of tzinfo.

Exceptions

`ProvenanceWriteError`	Raised when a rule's provenance record could not be written.
`UnresolvedArtifactError`	Raised when a declared output could not be resolved to a real artifact.

class makeprov.prov.ActivityNode(id, type, startedAtTime=None, endedAtTime=None, duration=None, wasAssociatedWith=None, qualifiedAssociation=None, used=None, generated=None, comment=None)

Bases: BaseNode

comment: str | None = None

duration: str | None = None

endedAtTime: datetime | None = None

generated: tuple[str | dict[str, Any], ...] | None = None

qualifiedAssociation: AssociationNode | str | dict[str, Any] | None = None

startedAtTime: datetime | None = None

used: tuple[FileEntity | str | dict[str, Any]] | None = None

wasAssociatedWith: AgentNode | str | dict[str, Any] | None = None

class makeprov.prov.AgentNode(id, type, label=None, hasVersion=None, source=None, operatingSystem=None)

Bases: BaseNode

hasVersion: str | None = None

label: str | None = None

operatingSystem: str | None = None

source: str | None = None

class makeprov.prov.AssociationNode(id, type, agent=None, hadPlan=None)

Bases: BaseNode

agent: AgentNode | str | dict[str, Any] | None = None

hadPlan: PlanNode | str | dict[str, Any] | None = None

class makeprov.prov.BaseNode(id, type)

Bases: RDFMixin

id: str

type: Any

class makeprov.prov.DepNode(id, type, label=None)

Bases: BaseNode

label: str | None = None

class makeprov.prov.EnvNode(id, type, label='Python environment', title=None, hasVersion=None, requires=None, resolved=None, wasDerivedFrom=None)

Bases: BaseNode

hasVersion: str | None = None

label: str = 'Python environment'

requires: tuple[DepNode] | None = None

resolved: tuple[DepNode] | None = None

title: str | None = None

wasDerivedFrom: str | None = None

class makeprov.prov.FileEntity(id, type, format=None, extent=None, modified=None, identifier=None, sha256=None, wasGeneratedBy=None)

Bases: BaseNode

extent: int | None = None

format: str | None = None

identifier: str | None = None

modified: datetime | None = None

sha256: str | None = None

wasGeneratedBy: ActivityNode | str | dict[str, Any] | None = None

class makeprov.prov.GraphEntity(id, type, wasGeneratedBy=None, wasAttributedTo=None, generatedAtTime=None)

Bases: BaseNode

generatedAtTime: datetime | None = None

wasAttributedTo: AgentNode | str | dict[str, Any] | None = None

wasGeneratedBy: ActivityNode | str | dict[str, Any] | None = None

class makeprov.prov.IriMinter(base_iri, prefix, pinned, file_segment='', repo_root=None)

Bases: object

Mints the identifiers for one provenance document.

Holds the base-IRI policy shared by the decorator API and the Snakemake bridge, so both name things the same way.

base_iri: str | None

file(path)

Return type:: str

file_segment: str = ''

mint(tail)

Return type:: str

pinned: bool

prefix: str

repo_root: Path | None = None

class makeprov.prov.PersonNode(id, type, name=None, email=None)

Bases: BaseNode

email: str | None = None

name: str | None = None

class makeprov.prov.PlanGraph(rule, requires=())

Bases: object

Prospective structure for one rule: its name and the rules it needs.

Kept separate from the retrospective record so a document can state what the workflow is without asserting that any of it ran.

requires: tuple[str, ...] = ()

rule: str

class makeprov.prov.PlanNode(id, type, label=None, hasVersion=None, source=None, requires=None)

Bases: BaseNode

The recipe an activity carried out, distinct from whoever ran it.

PROV separates the plan from the agent executing it. The script at a given commit is the plan; the Python runtime and the person invoking it are agents. Keeping them apart is what makes the graph mappable onto Workflow Run RO-Crate, whose instrument and agent are distinct slots.

hasVersion: str | None = None

label: str | None = None

requires: tuple[str, ...] | None = None

source: str | None = None

class makeprov.prov.Prov(base_iri, name, provenance, results, context=<factory>)

Bases: object

base_iri: str

context: dict

classmethod create(base_iri, name, run_id, t0, t1, inputs, outputs, results, success=True, metadata=None, activity_id=None, parent_id=None, record_user=False, record_environment=False, forge_profiles=None, plan_graph=None, origin=None, revision=None)

Assemble a provenance graph from rule execution details.

Parameters:

base_iri (str | None) – Base IRI for generated identifiers.
name (str) – Logical rule name.
run_id (str) – Unique identifier for this run, typically timestamp-based.
t0 (datetime) – Start time of the rule execution.
t1 (datetime) – End time of the rule execution.
inputs (list[ArtifactRef]) – Entities consumed by the rule. Local refs are hashed and stat-ed; external refs are cited by IRI.
outputs (list[ArtifactRef]) – Entities produced by the rule.
results (list[RDFMixin]) – Optional result graphs to embed alongside provenance records.
success (bool) – Whether the rule completed successfully.
record_user (bool) – Record the invoking user from git config as a schema:Person agent. Off by default, since provenance documents are routinely committed and published.
record_environment (bool) – Also record retrospective environment evidence: the distributions this run actually imported (pinned to exact versions, unlike the declared requires range specs), and a citation of any lockfile found (uv.lock, poetry.lock, Pipfile.lock, pdm.lock, pylock.toml). Off by default: a full dependency snapshot adds real document weight most rules don’t need.
origin (str | None) – Reuse an already-looked-up git config --get remote.origin.url instead of running it again, e.g. when a caller minted activity_id beforehand.
revision (str | None) – Reuse an already-looked-up git rev-parse HEAD instead of running it again.

Returns:

A populated Prov instance ready for serialization.

Return type:

Prov

Examples

prov = Prov.create(
    base_iri=None,
    name="uppercase",
    run_id="20240101T120000-1a2b3c4d",
    t0=start,
    t1=end,
    inputs=[ArtifactRef.local("input.txt")],
    outputs=[ArtifactRef.local("output.txt")],
    results=[],
)

classmethod merge(provs)

Combine multiple provenance documents into one.

Parameters:: provs (list[Prov]) – Provenance objects to merge.
Returns:: A new object containing combined provenance and results from all inputs.
Return type:: Prov

Examples

merged = Prov.merge([prov_a, prov_b])

name: str

provenance: list[RDFMixin]

results: tuple[GraphEntity, list[RDFMixin]]

to_graph(frame='provenance')

to_jsonld(frame='provenance', with_context=False)

Return type:: dict

write(prov_path, fmt='json', frame='provenance', context=False, context_url=None)

Serialize provenance to disk.

Parameters:

prov_path (str | Path) – Output path (without extension) where the provenance document should be written.
fmt (str) – Output format, "json" for JSON-LD or "trig" for RDF TriG.
frame (str) – Which structure to make primary subject of jsonld or trig named graph. Options: “provenance” or “results”.
context (bool) – Whether to include the JSON-LD context inline when writing JSON.

Returns:

The path to the written provenance document with extension.

Return type:

Path

Raises:

Exception – If the requested format is unsupported.

Examples

output = prov.write("prov/uppercase", fmt="json", context=True)

class makeprov.prov.ProvDoc(provenance=<factory>)

Bases: RDFMixin

provenance: tuple[RDFMixin]

exception makeprov.prov.ProvenanceWriteError

Bases: RuntimeError

Raised when a rule’s provenance record could not be written.

Under ProvenanceConfig’s default strict=True, this replaces the historical behavior of silently logging a warning and returning a successful result with no provenance on disk.

exception makeprov.prov.UnresolvedArtifactError

Bases: ProvenanceWriteError

Raised when a declared output could not be resolved to a real artifact.

A rule that reports success while one of its declared outputs is missing has either failed silently or mis-declared its outputs. Earlier versions dropped such artifacts from the graph without comment; that produced provenance which looked complete but wasn’t.

makeprov.prov.apply_context(node, context)

Bind a document-level context to a node and rebuild its term aliases.

Return type:: RDFMixin

makeprov.prov.pep503_normalize(name)

Normalize a package name according to PEP 503 rules.

Parameters:: name (str) – The distribution name to normalize.
Returns:: Lowercase, normalized package name with punctuation collapsed.
Return type:: str

makeprov.prov.project_metadata(dist_name=None)

Extract package metadata for provenance enrichment.

Parameters:: dist_name (str | None) – Distribution name; when None the caller’s package name is inferred from the module context.
Returns:: Distribution name, version, and dependency specifications. Empty values are returned when metadata cannot be found.
Return type:: tuple[str | None, str | None, list[str]]

Examples

name, version, requires = project_metadata("makeprov")

makeprov.prov.resolve_iris(base_iri, context, *, file_segment='', origin=None, revision=None, forge_profiles=None)

Decide how a document’s identifiers are minted.

An explicit base_iri is used as-is. Failing that, a remote on a known forge (see forges.toml) makes the repository URL the document’s @base and pins file identifiers to the current commit through a blob: prefix — pinning to the commit rather than the branch matters, since a branch URL names different bytes after every push. With neither, identifiers stay relative to the document, which is preferable to inventing a namespace that would collide across unrelated workflows.

context is mutated in place when the forge heuristic applies. origin and revision let a caller reuse git lookups it has already made.

Return type:: IriMinter

makeprov.prov.working_tree_is_dirty()

Whether the checkout has uncommitted changes.

Matters because a commit SHA recorded next to a dirty tree describes code that is not what actually ran.

Return type:: bool