makeprov.core

Functions

build(target[, _seen, session])	Recursively build a target and its prerequisites.
build_all(*[, session])	Build all concrete targets that have no dependents.
dataclass([cls, init, repr, eq, order, ...])	Add dunder methods based on the fields defined in the class.
dry_run_build(target, *[, session])	Log the steps required to build target without executing rules.
explain(target, *[, session])	Log the rule used for each target in build order.
field(*[, default, default_factory, init, ...])	Return an object to identify dataclass fields.
flush_prov_buffer(*[, prov_path, config, ...])	Write or propagate the most recent provenance buffer.
get_args(tp)	Get type arguments with all substitutions performed.
get_origin(tp)	Get the unsubscripted version of a type.
get_type_hints(obj[, globalns, localns, ...])	Return type hints for an object.
list_rules(*[, session])	Return registered rule names in alphabetical order.
list_targets(*[, session])	Return concrete targets produced by non-pattern rules.
needs_update(outputs, deps)	Determine whether outputs are stale relative to dependencies.
new_session()	Create a fresh session with isolated registries and buffers.
parse_compile(format[, extra_types, ...])	Create a Parser instance to parse "format".
plan(target, *[, session])	Return the execution order for building a target.
resolve_target(target, *[, session])	Resolve a target to its registered rule and parameters.
root_targets(*[, session])	Return concrete targets that are not dependencies of other rules.
rule(*[, name, phony, base_iri, prov_dir, ...])	Decorate a function as a build rule with automatic provenance.
start_prov_buffer(*[, session])	Create a provenance buffer to batch writes.
to_dot(target, *[, session])	Render the dependency graph for target in DOT format.

Classes

Any(*args, **kwargs)	Special type indicating an unconstrained type.
CachedDownload(url, cache_path, *[, ...])	Input wrapper that lazily downloads and records source metadata.
InDir(*paths)	Input directory that tracks files declared within it.
InPath(*paths)	Marker for input paths where "-" maps to stdin.
OutDir(*paths)	Output directory that tracks files declared within it.
OutPath(*paths)	Marker for output paths where "-" maps to stdout.
Parser(format[, extra_types, case_sensitive])	Encapsulate a format string that may be used to parse other strings.
Path(*args, **kwargs)	PurePath subclass that can make system calls.
Prov(base_iri, name, provenance, results[, ...])
ProvenanceConfig([base_iri, prov_dir, ...])	Runtime configuration for provenance generation.
RDFMixin()	Provide JSON-LD serialization helpers for dataclasses.
Rule(name, func[, deps, outputs, ...])	Minimal description of a build rule.
Session([rules_by_target, rules_by_name, ...])	In-memory registries and buffers for a makeprov run.
datetime(year, month, day[, hour[, minute[, ...)	The year, month and day arguments are required.
timezone	Fixed offset from UTC implementation of tzinfo.

class makeprov.core.Rule(name, func, deps=<factory>, outputs=<factory>, dep_templates=<factory>, out_templates=<factory>, out_parsers=<factory>, phony=False)

Bases: object

Minimal description of a build rule.

Rules capture the callable to execute, their declared dependencies and outputs, and optional parse templates for parameterized targets. Thin registry helpers in this module use these objects to resolve targets, explain the execution plan, and run builds.

dep_templates: list[str]

deps: list[str]

func: Callable

name: str

out_parsers: list[Parser]

out_templates: list[str]

outputs: list[str]

phony: bool = False

class makeprov.core.Session(rules_by_target=<factory>, rules_by_name=<factory>, pattern_rules=<factory>, commands=<factory>, prov_buffers=<factory>)

Bases: object

In-memory registries and buffers for a makeprov run.

commands: set[Callable]

pattern_rules: list[Rule]

prov_buffers: list[list[Prov]]

rules_by_name: dict[str, Rule]

rules_by_target: dict[str, Rule]

makeprov.core.build(target, _seen=None, *, session=None, **kwargs)

Recursively build a target and its prerequisites.

Parameters:

• target (OutPath) – Path to the output to build. Paths may be concrete or match templated outputs registered with rule().

• _seen (set[str] | None) – Internal set to detect graph cycles.

makeprov.core.build_all(*, session=None)

Build all concrete targets that have no dependents.

makeprov.core.dry_run_build(target, *, session=None)

Log the steps required to build target without executing rules.

Return type:

None

makeprov.core.explain(target, *, session=None)

Log the rule used for each target in build order.

Return type:

None

makeprov.core.flush_prov_buffer(*, prov_path=None, config=None, fmt=None, frame=None, context=None, context_url=None, session=None, label=None)

Write or propagate the most recent provenance buffer.

Returns the merged Prov object for the flushed buffer. When a parent buffer exists, the merged provenance is appended to it for further aggregation. When prov_path is provided, the merged provenance is written even if a parent buffer exists. Without a parent buffer, the merged provenance is written to disk using the provided configuration (falling back to the process-wide configuration via makeprov.ProvenanceConfig).

Return type:

Prov | None

makeprov.core.list_rules(*, session=None)

Return registered rule names in alphabetical order.

Return type:

list[str]

makeprov.core.list_targets(*, session=None)

Return concrete targets produced by non-pattern rules.

Return type:

list[str]

makeprov.core.needs_update(outputs, deps)

Determine whether outputs are stale relative to dependencies.

Parameters:

• outputs (Iterable[str | Path]) – Output files expected to exist after a rule runs.

• deps (Iterable[str | Path]) – Dependency files that must be newer than outputs for a rebuild to be unnecessary.

Returns:

True if any output is missing or older than a dependency; the absence of dependencies returns False to avoid unnecessary rebuilds.

Return type:

bool

Examples

from makeprov.core import needs_update

if needs_update(["data/output.txt"], ["data/input.txt"]):
    regenerate()

makeprov.core.new_session()

Create a fresh session with isolated registries and buffers.

Return type:

Session

makeprov.core.plan(target, *, session=None)

Return the execution order for building a target.

The plan is derived using resolve_target() for each dependency, ensuring concrete and templated rules are treated uniformly.

Return type:

list[tuple[str, Rule, dict[str, Any]]]

makeprov.core.resolve_target(target, *, session=None)

Resolve a target to its registered rule and parameters.

Concrete targets are looked up directly in RULES_BY_TARGET. Pattern rules are attempted in registration order using parse templates.

Return type:

tuple[Rule, dict[str, Any]]

makeprov.core.root_targets(*, session=None)

Return concrete targets that are not dependencies of other rules.

Return type:

list[str]

makeprov.core.rule(*, name=None, phony=False, base_iri=None, prov_dir=None, prov_path=None, force=None, dry_run=None, out_fmt=None, frame=None, config=None, context=None, merge=None, session=None)

Decorate a function as a build rule with automatic provenance.

Parameters:

• name (str | None) – Logical name for the rule; defaults to the function name.

• phony (bool) – When True, do not require an OutPath parameter and always execute the wrapped function regardless of timestamps. Useful for meta-rules such as aggregators or reporting commands.

• base_iri (str | None) – Base IRI for provenance identifiers; overrides global configuration when provided.

• prov_dir (str | None) – Directory where provenance documents are saved.

• prov_path (str | None) – Explicit path for the provenance file; overrides prov_dir when set.

• force (bool | None) – When True, always run the rule regardless of timestamps.

• dry_run (bool | None) – When True, log activity without executing the wrapped function.

• out_fmt (Optional[Literal['json', 'trig']]) – Output format for provenance files ("json" or "trig").

• frame (Optional[Literal['provenance', 'results']]) – Which structure to make primary subject of jsonld or trig named graph. Options: “provenance” or “results”.

• config (ProvenanceConfig | None) – Configuration object to use instead of the process-wide configuration returned by makeprov.ProvenanceConfig.

• context (bool | None) – Whether to embed JSON-LD context in output when writing provenance.

• merge (bool | None) – When True, buffer provenance for this rule and any nested rule calls, emitting a single merged document. Defaults to the configured merge behavior.

• session (Session | None) – Registry and buffer container to use instead of the process-wide default session. Passing a dedicated session isolates rules, commands, and provenance buffers from other runs.

Returns:

A decorator that wraps the target function and registers it as a rule when outputs are discoverable from annotations. Templated InPath or OutPath defaults using str.format style placeholders (e.g. "data/{sample:d}.txt") register as pattern rules and are resolved dynamically for matching targets.

Return type:

Callable

Examples

Annotate parameters with InPath and OutPath to let the decorator infer dependencies:

from makeprov import InPath, OutPath, rule

@rule()
def uppercase(src: InPath, dst: OutPath):
    dst.write_text(src.read_text().upper())

uppercase("data/input.txt", "data/output.txt")

makeprov.core.start_prov_buffer(*, session=None)

Create a provenance buffer to batch writes.

Buffers capture provenance from multiple rule invocations and emit a single merged document when flushed. Callers should prefer one top-level buffer per workflow run; nested buffers are supported for backward compatibility but are avoided by the public APIs to keep merge semantics predictable.

Return type:

None

makeprov.core.to_dot(target, *, session=None)

Render the dependency graph for target in DOT format.

Return type:

str