API reference¶

Run¶

class rec.Run(observers: Sequence[BaseObserver] = (), run_id: str | None = None, pre_run_hooks: list = None, post_run_hooks: list = None)¶

Coordinate one execution and forward its provenance to observers.

Args:: observers: Storage backends that receive every run event. run_id: Canonical REC run identifier. A UUID-based ID is generated when omitted. pre_run_hooks: Callables run after the run starts. post_run_hooks: Callables run after successful completion.

add_activity(activity_id: str, activity_type: str, associated_with=None)¶: Add a PROV activity and optionally associate it with an agent.

add_agent(agent_id: str, agent_type: str)¶: Add a PROV agent with the supplied identifier and RDF type.

add_artefact(filename, gen_activity=None, generated_time=None, title=None, archive_path=None, sha256=None, size_bytes=None)¶: Record an artefact generated by an activity, with optional file metadata.

add_resource(filename, usage_activity=None, usage_time=None, title=None, archive_path=None, sha256=None, size_bytes=None)¶: Record a resource used by an activity, including optional file metadata.

info()¶: Return the run ID, lifecycle type, timestamps, and result.

log_dependencies(dependencies)¶: Record dependency metadata rows with a name and optional version.

log_host_info(host_info)¶: Record host metadata such as hostname, operating system, and runtime.

log_repositories(repositories)¶: Record repository metadata rows such as name, URL, and revision.

log_scalar(metric_name, value, step: int = None)¶: Record a dimensionless scalar metric, optionally at a step.

log_sources(sources)¶: Record source-file metadata rows containing at least a path.

main()¶

Execute the work represented by this run.

Subclasses override this method and return their result.

run()¶: Run main and record completion, failure, or interruption.

Observers¶

class rec.observers.FileObserver(path, file_id=None)¶

Persist one REC graph as JSON-LD.

Args:: path: Archive file to create or reopen. file_id: Stable archive identity. Generated for a new archive.

add_activity(activity_id, activity_type, associated_with=None)¶: Add a PROV activity and optionally associate it with an agent.

add_agent(agent_id, agent_type)¶: Add a PROV agent to the run.

add_artefact(path, generated_by, generated_at, label=None, sha256=None, size_bytes=None, archive_path=None)¶: Record a PROV entity generated by an activity at a specific time.

add_resource(path, used_by, used_at, label=None, sha256=None, size_bytes=None, archive_path=None)¶: Record a PROV entity used by an activity at a specific time.

close()¶: Flush the current graph to the storage backend.

log_cancelled_run(cancelled_time: datetime)¶: Record cancellation at cancelled_time.

log_completed_run(completed_time: datetime)¶: Record successful completion at completed_time.

log_dependencies(dependencies)¶: Record dependency rows with name and optional version metadata.

log_failed_run(failed_time: datetime)¶: Record failure at failed_time.

log_host_info(host_info)¶: Record the host’s hostname, operating system, and runtime metadata.

log_interrupted_run(interrupted_time: datetime)¶: Record interruption at interrupted_time.

log_queued_run(run_id: str)¶: Record run_id as a queued REC run.

log_repositories(repositories)¶: Record repository rows with name, URL, and revision metadata.

log_run_heartbeat(beat_time: datetime, result: object | None)¶: Record a heartbeat and its optional current result.

log_scalar(metric_name, value, step=None)¶: Record a dimensionless QUDT metric, optionally at a step.

log_sources(sources)¶: Record source-file rows containing path and optional file metadata.

log_started_run(run_id: str, started_time: datetime) → str¶: Record the start time and return the canonical run ID.

query_active_run()¶: Return this observer’s running ID, or None when it is not running.

property run¶: Return the RDF subject for the current run.

serialize()¶: Return the current REC graph as compact JSON-LD.

class rec.observers.MariaDBObserver(run_id=None, db_name='logbook', table='runs')¶

Persist REC JSON-LD in MariaDB and import file archives.

Args:: run_id: Existing run to reopen, or an ID generated for a new run. db_name: Database selected from the configured MariaDB server. table: Base table name for runs and file-source mappings.

add_activity(activity_id, activity_type, associated_with=None)¶: Add a PROV activity and optionally associate it with an agent.

add_agent(agent_id, agent_type)¶: Add a PROV agent to the run.

add_artefact(path, generated_by, generated_at, label=None, sha256=None, size_bytes=None, archive_path=None)¶: Record a PROV entity generated by an activity at a specific time.

add_resource(path, used_by, used_at, label=None, sha256=None, size_bytes=None, archive_path=None)¶: Record a PROV entity used by an activity at a specific time.

close()¶: Flush a live run, then close the database cursor and connection.

log_cancelled_run(cancelled_time: datetime)¶: Record cancellation at cancelled_time.

log_completed_run(completed_time: datetime)¶: Record successful completion at completed_time.

log_dependencies(dependencies)¶: Record dependency rows with name and optional version metadata.

log_failed_run(failed_time: datetime)¶: Record failure at failed_time.

log_host_info(host_info)¶: Record the host’s hostname, operating system, and runtime metadata.

log_interrupted_run(interrupted_time: datetime)¶: Record interruption at interrupted_time.

log_queued_run(run_id: str)¶: Record run_id as a queued REC run.

log_repositories(repositories)¶: Record repository rows with name, URL, and revision metadata.

log_run_heartbeat(beat_time: datetime, result: object | None)¶: Record a heartbeat and its optional current result.

log_scalar(metric_name, value, step=None)¶: Record a dimensionless QUDT metric, optionally at a step.

log_sources(sources)¶: Record source-file rows containing path and optional file metadata.

log_started_run(run_id: str, started_time: datetime) → str¶: Record the start time and return the canonical run ID.

query_active_run()¶: Return one currently running database run, if present.

property run¶: Return the RDF subject for the current run.

serialize()¶: Return the current REC graph as compact JSON-LD.

set_file_source(file_id, archive_path)¶: Associate this live database run with its file-backed source.

sync_file(path)¶: Import one file-backed run without changing its REC identities.

sync_files(directory, started_after=None)¶: Import archive files in start-time order, optionally after a cursor.

Lifecycle types¶

class rec.run.RunStatus¶: REC lifecycle RDF types exposed by Run.status.