API Reference

The module-level Python APIs below are available for direct integration but are experimental during the 0.x series. They may change between minor releases. The command-line interface and fields governed by an explicit provenance schema version are the clearer compatibility contracts. Review the changelog before upgrading code that imports these modules directly.

Capture portable provenance metadata for data-processing outputs.

class reprotrail.provenance.GitState(repo_root, commit, branch, remote_url, dirty, dirty_marker, status_short, diff_hash=None)

Snapshot of a Git repository at one point in time.

Parameters:

• repo_root (Path)

• commit (str | None)

• branch (str | None)

• remote_url (str | None)

• dirty (bool)

• dirty_marker (str)

• status_short (str)

• diff_hash (str | None)

class reprotrail.provenance.InputPathState(path, exists, kind, backend, metadata, git_state=None, git_path=None, git_status='', error=None)

Snapshot of an input path and metadata that identifies it.

Parameters:

• path (Path)

• exists (bool)

• kind (str)

• backend (Literal['git-lfs', 'dvc', 'git', 'filesystem', 'unknown'])

• metadata (dict[str, Any])

• git_state (GitState | None)

• git_path (str | None)

• git_status (str)

• error (str | None)

reprotrail.provenance.canonicalize_remote_url(remote_url)

Return a portable, reader-friendly form of a Git remote URL.

Parameters:

remote_url (str | None)

Return type:

str | None

reprotrail.provenance.run_git(args, cwd)

Run Git and return (ok, stdout, error) without raising.

Parameters:

• args (Sequence[str])

• cwd (Path | str)

Return type:

tuple[bool, str, str]

reprotrail.provenance.discover_repo_root(repo_dir=None, *, max_parent_levels=3)

Find the Git repository root for a directory or one of its parents.

Parameters:

• repo_dir (Path | str | None)

• max_parent_levels (int)

Return type:

Path | None

reprotrail.provenance.get_git_state(repo_dir='.', *, remote='origin', include_diff_hash=True)

Capture the current Git state for a repository.

Parameters:

• repo_dir (Path | str)

• remote (str)

• include_diff_hash (bool)

Return type:

GitState

reprotrail.provenance.public_git_state(state)

Return a portable Git state record suitable for public metadata.

Parameters:

state (GitState | Mapping[str, Any])

Return type:

dict[str, Any]

reprotrail.provenance.summarize_directory(path, *, max_entries=20000)

Summarize a directory without embedding a full file listing.

Parameters:

• path (Path | str)

• max_entries (int)

Return type:

dict[str, Any]

reprotrail.provenance.get_input_path_state(path)

Inspect one input path and classify its provenance backend.

Parameters:

path (Path | str)

Return type:

InputPathState

reprotrail.provenance.get_input_path_states(paths)

Inspect multiple input paths, preserving input order.

Parameters:

paths (Iterable[Path | str])

Return type:

list[InputPathState]

reprotrail.provenance.public_input_path_state(state)

Return a compact input path record without local-only repository roots.

Parameters:

state (InputPathState | Mapping[str, Any])

Return type:

dict[str, Any]

reprotrail.provenance.public_provenance(value)

Return provenance metadata intended to be written into public outputs.

Parameters:

value (Any)

Return type:

Any

reprotrail.provenance.clean_command_parts(parts)

Remove reprotrail/provenance sidecar flags from recorded commands.

Parameters:

parts (Sequence[str])

Return type:

list[str]

reprotrail.provenance.build_cf_history_entry(command=None, *, git_state=None, git_states=(), input_states=(), timestamp=None, include_inputs=False)

Build a timestamped history line suitable for CF/xarray attrs.

Parameters:

• command (str | Sequence[str] | None)

• git_state (GitState | Mapping[str, Any] | None)

• git_states (Sequence[GitState | Mapping[str, Any]])

• input_states (Sequence[InputPathState | Mapping[str, Any]])

• timestamp (datetime | None)

• include_inputs (bool)

Return type:

str

reprotrail.provenance.append_cf_history(existing, entry)

Prepend a new entry to existing CF history text.

Parameters:

• existing (str | None)

• entry (str)

Return type:

str

reprotrail.provenance.append_xarray_history(obj, entry, *, copy=False)

Prepend a history entry to an xarray-like object’s attrs.

Parameters:

• obj (Any)

• entry (str)

• copy (bool)

Return type:

Any

reprotrail.provenance.enforce_clean_repos(repos, *, allow_dirty=False, missing_ok=True)

Validate that repositories are clean unless dirty state is allowed.

Parameters:

• repos (Iterable[Path | str])

• allow_dirty (bool)

• missing_ok (bool)

Return type:

list[GitState]

reprotrail.provenance.env_allows_dirty(var='REPROTRAIL_ALLOW_DIRTY')

Return whether an environment variable opts into dirty repositories.

Parameters:

var (str)

Return type:

bool

Pixi environment and editable dependency helpers.

exception reprotrail.pixi.PixiGitFreshnessError

Raised when Pixi Git freshness cannot be checked safely.

reprotrail.pixi.pixi_environment_block(lock_text, environment)

Return the environment block from a Pixi lockfile.

Parameters:

• lock_text (str)

• environment (str | None)

Return type:

str

reprotrail.pixi.is_local_pixi_ref(value)

Return whether a Pixi pypi reference points at a local path.

Parameters:

value (str)

Return type:

bool

reprotrail.pixi.pixi_local_path_dependencies(lock_text, environment)

List local path dependencies in one Pixi environment.

Parameters:

• lock_text (str)

• environment (str | None)

Return type:

list[str]

reprotrail.pixi.pixi_package_names_by_pypi(lock_text)

Return package names keyed by Pixi pypi source reference.

Parameters:

lock_text (str)

Return type:

dict[str, str]

reprotrail.pixi.pixi_dependency_records(lock_text, environment, project_root)

Classify local Pixi dependencies as project-self or external-editable.

Parameters:

• lock_text (str)

• environment (str | None)

• project_root (Path)

Return type:

list[dict[str, Any]]

reprotrail.pixi.public_dependency_records(records)

Remove private resolved-path fields from dependency records.

Parameters:

records (list[dict[str, Any]])

Return type:

list[dict[str, Any]]

reprotrail.pixi.editable_dependency_failures(dependency_records, *, allow_editable)

Return policy failures for external editable/path dependencies.

Parameters:

• dependency_records (list[dict[str, Any]])

• allow_editable (bool)

Return type:

list[str]

reprotrail.pixi.repo_paths_with_dependencies(repos, dependency_records)

Append resolved editable dependency Git repos to an inspected repo list.

Parameters:

• repos (list[str])

• dependency_records (list[dict[str, Any]])

Return type:

list[str]

reprotrail.pixi.normalize_package_name(name)

Return a normalized Python distribution name.

Parameters:

name (str)

Return type:

str

reprotrail.pixi.package_records(package_names)

Return installed package records with sanitized source identity.

Parameters:

package_names (list[str] | tuple[str, ...])

Return type:

list[dict[str, Any]]

reprotrail.pixi.package_versions(package_names)

Return installed versions for package names that can be resolved.

Parameters:

package_names (list[str] | tuple[str, ...])

Return type:

dict[str, str]

reprotrail.pixi.pixi_package_license_records(project_root, pixi_environment)

Return package license metadata from the local Pixi environment.

Parameters:

• project_root (Path)

• pixi_environment (str | None)

Return type:

list[dict[str, Any]]

reprotrail.pixi.check_pixi_git_freshness(project_root, environment, packages, *, manifest_path=None)

Check whether selected Git-backed Pixi packages would move on update.

Parameters:

• project_root (Path)

• environment (str)

• packages (tuple[str, ...])

• manifest_path (Path | None)

Return type:

dict[str, Any]

reprotrail.pixi.infer_pixi_environment(project_root, value=None)

Infer the active Pixi environment from an explicit value, env var, or Python.

Parameters:

• project_root (Path)

• value (str | None)

Return type:

str | None

reprotrail.pixi.environment_summary(*, project_root, pixi_environment, dependency_records, allow_editable, package_names, env_var_whitelist)

Build a portable summary of the active runtime environment.

Parameters:

• project_root (Path)

• pixi_environment (str | None)

• dependency_records (list[dict[str, Any]])

• allow_editable (bool)

• package_names (tuple[str, ...])

• env_var_whitelist (tuple[str, ...])

Return type:

dict[str, Any]

reprotrail.pixi.write_environment_bundle(*, run_root, project_root, lockfile, pixi_environment, dependency_records, allow_editable, package_names, env_var_whitelist)

Copy a Pixi lockfile and environment summary into provenance artifacts.

Parameters:

• run_root (Path)

• project_root (Path)

• lockfile (Path)

• pixi_environment (str | None)

• dependency_records (list[dict[str, Any]])

• allow_editable (bool)

• package_names (tuple[str, ...])

• env_var_whitelist (tuple[str, ...])

Return type:

dict[str, Any]

Command runner that records provenance and runtime status.

exception reprotrail.runner.RunError

Raised when the runner cannot start or finish safely.

reprotrail.runner.diagnostic_software_states(*, candidates, trusted_states, log)

Return configured repo states that are not trusted runtime repos.

Parameters:

• candidates (list[str])

• trusted_states (list[dict[str, Any]])

• log (Path)

Return type:

list[dict[str, Any]]

reprotrail.runner.merge_declared_inputs(declared_states, child_records)

Keep declared inputs alongside input records written by the child.

Parameters:

• declared_states (list[InputPathState])

• child_records (list[InputPathState | Mapping[str, Any]])

Return type:

list[dict[str, Any]]

reprotrail.runner.run_with_provenance(*, command, log, repos=None, allow_dirty=False, allow_editable=False, allow_partial_metadata=False, provenance_json=None, product_output=None, inputs=None, settings=None)

Run a command while recording v1 reprotrail provenance.

Parameters:

• command (list[str])

• log (str | Path)

• repos (list[str] | None)

• allow_dirty (bool)

• allow_editable (bool)

• allow_partial_metadata (bool)

• provenance_json (str | Path | None)

• product_output (str | Path | None)

• inputs (list[str | Path] | None)

• settings (ReprotrailSettings | None)

Return type:

dict[str, Any]

Dependency snapshot contracts and product environment audits.

reprotrail.epochs.build_dependency_snapshot(*, project_root, lockfile=None, pixi_environment=None, package_versions_payload=None, runtime_packages_payload=None, dependency_records=None, software_states=None, package_names=('reprotrail',))

Build a stable dependency/runtime snapshot.

Parameters:

• project_root (Path)

• lockfile (Path | None)

• pixi_environment (str | None)

• package_versions_payload (dict[str, str] | None)

• runtime_packages_payload (list[dict[str, Any]] | None)

• dependency_records (list[dict[str, Any]] | None)

• software_states (list[dict[str, Any]] | None)

• package_names (tuple[str, ...])

Return type:

dict[str, Any]

reprotrail.epochs.check_dependency_contract(*, run_root, project_root, acceptance_reason=None, dry_run=False, pixi_environment=None, snapshot=None, package_names=('reprotrail',))

Check or accept the dependency epoch for a run root.

Parameters:

• run_root (Path)

• project_root (Path)

• acceptance_reason (str | None)

• dry_run (bool)

• pixi_environment (str | None)

• snapshot (dict[str, Any] | None)

• package_names (tuple[str, ...])

Return type:

dict[str, Any]

reprotrail.epochs.annotate_product_environment_consistency(provenance_path, *, run_root, output_snapshot, output_epoch, append_readme=False)

Annotate a product with input/output dependency-epoch consistency.

Parameters:

• provenance_path (Path | None)

• run_root (Path | None)

• output_snapshot (dict[str, Any])

• output_epoch (dict[str, Any] | None)

• append_readme (bool)

Return type:

dict[str, Any] | None

reprotrail.epochs.audit_dependency_epochs(*, run_root, output, product_provenance=None, product_root_markers=())

Scan product provenance files and summarize accepted dependency epochs.

Parameters:

• run_root (Path)

• output (Path)

• product_provenance (list[Path] | None)

• product_root_markers (tuple[str, ...])

Return type:

dict[str, Any]

Product sidecar, checksum, and pointer-attribute helpers.

class reprotrail.products.ProductSidecars(data, package, stem, readme, license, ro_crate, provenance, provenance_sha256)

Paths that travel with one durable data product.

Parameters:

• data (Path)

• package (Path)

• stem (str)

• readme (Path)

• license (Path)

• ro_crate (Path)

• provenance (Path)

• provenance_sha256 (Path)

reprotrail.products.product_sidecars(data_path)

Return sidecar paths for a durable data product.

Parameters:

data_path (str | Path)

Return type:

ProductSidecars

reprotrail.products.product_record(data_path, *, provenance_path=None, metadata=None)

Build generic product metadata for a provenance record.

Parameters:

• data_path (str | Path)

• provenance_path (str | Path | None)

• metadata (Mapping[str, Any] | None)

Return type:

dict[str, Any]

reprotrail.products.public_license(license_payload)

Validate and normalize required product license metadata.

Parameters:

license_payload (str | Mapping[str, Any] | None)

Return type:

dict[str, str]

reprotrail.products.default_readme_template_text()

Return the bundled product README template.

Return type:

str

reprotrail.products.copy_readme_template(output, *, force=False)

Copy the bundled product README template for project customization.

Parameters:

• output (str | Path)

• force (bool)

Return type:

Path

reprotrail.products.write_json_with_provenance(path, payload, *, provenance=None)

Write JSON metadata, embedding public provenance when supplied.

Parameters:

• path (str | Path)

• payload (dict[str, Any])

• provenance (dict[str, Any] | None)

Return type:

None

reprotrail.products.stamp_dataset_provenance(obj, provenance)

Stamp lightweight provenance pointer attrs on an xarray-like object.

Parameters:

• obj (Any)

• provenance (dict[str, Any] | None)

Return type:

Any

reprotrail.products.finalize_product_provenance(provenance_path, *, project_root=None, pixi_environment=None, product_metadata_file='reprotrail.products.toml', license=None, allow_partial_metadata=False, stamp=True)

Finalize a product sidecar checksum and lightweight product attrs.

Parameters:

• provenance_path (str | Path)

• project_root (str | Path | None)

• pixi_environment (str | None)

• product_metadata_file (str)

• license (str | Mapping[str, Any] | None)

• allow_partial_metadata (bool)

• stamp (bool)

Return type:

str | None

Product license, attribution, and packaging metadata helpers.

exception reprotrail.product_metadata.ProductMetadataError

Raised when product metadata cannot be resolved safely.

exception reprotrail.product_metadata.ProductMetadataDependencyError

Raised when optional product metadata dependencies are unavailable.

class reprotrail.product_metadata.ProductInput(name=None, producer=None, path=None, license=None, url=None, marginal=False)

Attribution and license metadata for one product input.

Parameters:

• name (str | None)

• producer (str | None)

• path (str | None)

• license (str | None)

• url (str | None)

• marginal (bool)

class reprotrail.product_metadata.SoftwareLicenseOverride(name, kind='package', license=None, url=None)

Manual license metadata for one software package or repository.

Parameters:

• name (str)

• kind (str)

• license (str | None)

• url (str | None)

class reprotrail.product_metadata.ProductMetadata(output, license=None, readme_template=None, inputs=(), software=(), source=None)

Metadata selected for one product output.

Parameters:

• output (str)

• license (str | None)

• readme_template (str | None)

• inputs (tuple[ProductInput, ...])

• software (tuple[SoftwareLicenseOverride, ...])

• source (Path | None)

reprotrail.product_metadata.load_product_index(project_root, *, metadata_file='reprotrail.products.toml')

Load project-root product metadata entries if the index exists.

Parameters:

• project_root (str | Path)

• metadata_file (str)

Return type:

tuple[ProductMetadata, …]

reprotrail.product_metadata.product_match_value(path, project_root)

Return the project-relative path string used for product metadata matching.

Parameters:

• path (str | Path)

• project_root (str | Path)

Return type:

str

reprotrail.product_metadata.match_product_metadata(product_output, project_root, *, metadata_file='reprotrail.products.toml')

Return the single product metadata entry matching one product output.

Parameters:

• product_output (str | Path)

• project_root (str | Path)

• metadata_file (str)

Return type:

ProductMetadata | None

reprotrail.product_metadata.require_product_metadata_tools()

Fail clearly when product license/RO-Crate dependencies are unavailable.

Return type:

None

reprotrail.product_metadata.normalize_spdx_expression(expression)

Validate and normalize an SPDX expression using the SPDX toolchain.

Parameters:

expression (str)

Return type:

str

reprotrail.product_metadata.spdx_expression_symbols(expression)

Return SPDX license symbols from a validated expression.

Parameters:

expression (str)

Return type:

list[str]

reprotrail.product_metadata.product_license_summary(value)

Return the short public license summary stored in provenance.

Parameters:

value (str | Mapping[str, Any] | None)

Return type:

dict[str, str] | None

reprotrail.product_metadata.input_license_records(inputs, *, project_root, package_dir)

Build attribution/license evidence records for product-index inputs.

Parameters:

• inputs (tuple[ProductInput, ...])

• project_root (str | Path)

• package_dir (str | Path)

Return type:

list[dict[str, Any]]

reprotrail.product_metadata.software_license_records(*, project_root, pixi_environment, overrides)

Build software/dependency license evidence records.

Parameters:

• project_root (str | Path)

• pixi_environment (str | None)

• overrides (tuple[SoftwareLicenseOverride, ...])

Return type:

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

Reproduce a recorded provenance step in a fresh workspace.

exception reprotrail.reproduce.ReproductionError

Raised when a reproduction setup cannot proceed.

reprotrail.reproduce.reproduce_from_provenance(*, provenance, workspace, execute=False, strict=False, env=None, project_repo=None, repo_sources=None, input_maps=None, resume=False, force=False, install=True)

Create a reproduction workspace from a product provenance sidecar.

Parameters:

• provenance (str | Path)

• workspace (str | Path)

• execute (bool)

• strict (bool)

• env (str | None)

• project_repo (str | None)

• repo_sources (dict[str, str] | None)

• input_maps (dict[str, str] | None)

• resume (bool)

• force (bool)

• install (bool)

Return type:

dict[str, Any]

Command-line interface for reprotrail.