rocrate_action_recorder¶

RO-Crate action recorder for CLI invocations.

Submodules¶

Classes¶

`IOArgumentNames`	Which argument names have values that are input/output files or directories.
`IOArgumentPath`	Container for the details of an input/output argument.
`IOArgumentPaths`	Container for all the input/output paths for a recording.
`Program`	Container for program details.

Functions¶

`record_argparse`(→ pathlib.Path)	Record a CLI invocation in an RO-Crate using argparse.
`recorded_argparse`(...)	Decorator to record a CLI invocation in an RO-Crate using argparse.
`playback`(→ str)	Extract and return recorded action commands sorted by execution time.
`record`(→ pathlib.Path)	Record a CLI invocation in an RO-Crate.

Package Contents¶

class rocrate_action_recorder.IOArgumentNames[source]¶

Which argument names have values that are input/output files or directories.

input_files: list[str]¶: List of argument names for input files.

output_files: list[str]¶: List of argument names for output files.

input_dirs: list[str]¶: List of argument names for input directories.

output_dirs: list[str]¶: List of argument names for output directories.

rocrate_action_recorder.record_argparse(parser: argparse.ArgumentParser, ns: argparse.Namespace, ios: rocrate_action_recorder.adapters.shared.IOArgumentNames, start_time: datetime.datetime, crate_dir: pathlib.Path | None = None, argv: list[str] | None = None, end_time: datetime.datetime | None = None, current_user: str | None = None, software_version: str | None = None, dataset_license: str | None = None) → pathlib.Path[source]¶

Record a CLI invocation in an RO-Crate using argparse.

Hint

The argument names passed in IOArgumentNames should be attributes on a argparse.Namespace object returned by parse_args(). For example parser.add_argument(’–input-file’) would correspond to argument name input_file.

Warning

A RO-Crate can only be written to the directory that contains all the input/output files and directories.

Parameters:

parser – The argparse.ArgumentParser used to parse the arguments.
ns – The argparse.Namespace with parsed arguments.
ios – The argument names that are inputs/outputs files/directories.
start_time – The datetime when the action started.
crate_dir – Optional path to the RO-Crate directory. If None, uses current working directory.
argv – Optional list of command-line arguments. If None, uses sys.argv.
end_time – Optional datetime when the action ended. If None, uses current time.
current_user – Optional username of the user running the action. If None, attempts to determine it from the system.
software_version – Optional version string of the software. If None, attempts to detect it automatically.
dataset_license – Optional license string to set for the RO-Crate dataset.

Returns:

Path to the generated ro-crate-metadata.json file.

Raises:

ValueError – If the current user cannot be determined. If the specified paths are outside the crate root. If the software version cannot be determined based on the program name.
MissingDestArgparseSubparserError – If parser has subparsers but dest is not set.

rocrate_action_recorder.recorded_argparse(parser: argparse.ArgumentParser | None = None, parser_argument: str | None = None, input_dirs: list[str] | None = None, output_dirs: list[str] | None = None, input_files: list[str] | None = None, output_files: list[str] | None = None, dataset_license: str | None = None, enabled_argument: str | None = None, crate_dir: pathlib.Path | None = None, crate_dir_argument: str | None = None) → collections.abc.Callable[[collections.abc.Callable[[argparse.Namespace], recorded_argparse.T]], collections.abc.Callable[[argparse.Namespace], recorded_argparse.T]][source]¶

Decorator to record a CLI invocation in an RO-Crate using argparse.

Hint

The argument names should be attributes on a argparse.Namespace object returned by parse_args(). For example parser.add_argument(’–input-file’) would correspond to argument name input_file.

Warning

A RO-Crate can only be written to the directory that contains all the input/output files and directories.

Parameters:

parser – The argument parser used to parse the command-line arguments. This is needed to extract program information and help texts for the arguments. Can not be used together with the parser_argument parameter.
parser_argument – The name of the attribute in argparse.Namespace object that contains the argparse.ArgumentParser object. Can not be used together with the parser parameter.
input_dirs – List of argument names representing input directories
output_dirs – List of argument names representing output directories
input_files – List of argument names representing input files
output_files – List of argument names representing output files
dataset_license – License string for the dataset. Use license identifiers from https://spdx.org/licenses/ if possible. If None, no license is recorded.
enabled_argument – Name of the attribute in args that indicates whether to record the invocation. Records if None. If provided, the invocation is only recorded if getattr(args, enabled_argument) is truthy.
crate_dir – Optional path to the RO-Crate directory. If None, uses current working directory. Can not be used together with the crate_dir_argument parameter.
crate_dir_argument – Name of the attribute in args that specifies the RO-Crate directory. If None, uses the current working directory. Can not be used together with the crate_dir parameter.

Returns:

Decorator function

Raises:

ValueError – If the current user cannot be determined. If the specified paths are outside the crate root. If the software version cannot be determined based on the program name. If both crate_dir and crate_dir_argument are specified. If both parser and parser_argument are specified. If parser_argument is specified but does not point to an ArgumentParser instance.
AttributeError – If parser_argument is specified but not found in args.
MissingDestArgparseSubparserError – If parser has subparsers but dest is not set.

class rocrate_action_recorder.IOArgumentPath[source]¶

Container for the details of an input/output argument.

name: str¶: The name of the argument as known in the parser with – stripped.

path: pathlib.Path¶: The path value of the argument.

help: str¶: Help text associated with the argument.

class rocrate_action_recorder.IOArgumentPaths[source]¶

Container for all the input/output paths for a recording.

input_files: list[IOArgumentPath]¶: List of input file argument paths.

output_files: list[IOArgumentPath]¶: List of output file argument paths.

input_dirs: list[IOArgumentPath]¶: List of input directory argument paths.

output_dirs: list[IOArgumentPath]¶: List of output directory argument paths.

class rocrate_action_recorder.Program[source]¶

Container for program details.

name: str¶: Name of the program.

description: str¶: Description of the program.

subcommands: dict[str, Program]¶: Dictionary of subcommand names to Program instances. Only contains used by current action.

version: str | None = None¶: Version of the program. If None, will be detected automatically.

rocrate_action_recorder.playback(crate_root: pathlib.Path) → str[source]¶

Extract and return recorded action commands sorted by execution time.

Parameters:: crate_root – Root directory of the RO-Crate.
Returns:: Newline-separated string of action command lines, sorted by endTime. Returns empty string if no actions are recorded.

rocrate_action_recorder.record(program: Program, ioargs: IOArgumentPaths, start_time: datetime.datetime, crate_dir: pathlib.Path | None = None, argv: list[str] | None = None, end_time: datetime.datetime | None = None, current_user: str | None = None, dataset_license: str | None = None) → pathlib.Path[source]¶

Record a CLI invocation in an RO-Crate.

This is a low-level function, better use one of the adapter functions for specific argument parsing frameworks like record_argparse() or record_cyclopts().

Example

Example with single input and output file arguments:

from datetime import datetime, UTC
from pathlib import Path

from rocrate_action_recorder import (
    IOArgumentPath,
    IOArgumentPaths,
    Program,
    record,
)

crate_dir = Path()
input_path = crate_dir / "input.txt"
output_path = crate_dir / "output.txt"
input_path.write_text("Hello World")
argv = [
    "myscript",
    "--input",
    str(input_path),
    "--output",
    str(output_path),
]
start_time = datetime(2026, 1, 16, 12, 0, 0, tzinfo=UTC)
# Simulate the script's main operation
output_path.write_text(input_path.read_text().upper())
end_time = datetime(2026, 1, 16, 12, 0, 5, tzinfo=UTC)

crate_meta = record(
    program=Program(
        name="myscript", description="My test script", version="1.2.3"
    ),
    ioargs=IOArgumentPaths(
        input_files=[
            IOArgumentPath(name="input", path=input_path, help="Input file")
        ],
        output_files=[
            IOArgumentPath(name="output", path=output_path, help="Output file")
        ],
    ),
    argv=argv,
    current_user="tester",
    start_time=start_time,
    end_time=end_time,
    crate_dir=crate_dir,
    dataset_license="CC-BY-4.0",
)
# crate_meta == Path("ro-crate-metadata.json")

Parameters:

program – The program details.
ioargs – Which files/directories are involved in action.
start_time – The datetime when the action started.
crate_dir – Optional path to the RO-Crate directory. If None, uses current working directory.
argv – Optional list of command-line arguments. If None, uses sys.argv.
end_time – Optional datetime when the action ended. If None, uses current time.
current_user – Optional username of the user running the action. If None, attempts to determine it from the system.
dataset_license – Optional license string to set for the RO-Crate dataset. For example “CC-BY-4.0”.

Returns:

Path to the generated ro-crate-metadata.json file.

Raises:

ValueError – If the current user cannot be determined. If the specified paths are outside the crate root. If the software version cannot be determined based on the program name. If start_time and end_time have different timezone information. If start_time is after end_time.