rocrate-action-recorder 0.1.0

Record calls of Python CLI commands into a Research Object Crate

rocrate-action-recorder

Python package to record calls of Python CLI commands into a Research Object Crate (RO-Crate).

Supports RO-Crate 1.1 specification. Specifically the Process Run Crate profile.

Install

pip install rocrate-action-recorder

Usage

Shown is an example of recording a CLI command (example-cli input.txt output.txt) implemented with argparse.

import argparse
from datetime import datetime
from pathlib import Path
from rocrate_action_recorder import record_with_argparse, IOArgumentNames

# Create an argparse parser
parser = argparse.ArgumentParser(prog="example-cli", description="Example CLI")
parser.add_argument("--version", action="version", version="1.2.3")
parser.add_argument("input", type=Path, help="Input file")
parser.add_argument("output", type=Path, help="Output file")

# Prepare input
Path("input.txt").write_text("hello")

# Parse arguments
args = ['input.txt', 'output.txt']
ns = parser.parse_args(args)

# Do handling of the CLI command here
start_time = datetime.now()
# For demonstration, just upper case input to output
Path(ns.output).write_text(ns.input.read_text().upper())

record_with_argparse(
    parser, 
    ns, 
    # Tell recorder which arguments are for input and output files
    IOArgumentNames(input_files=["input"], output_files=["output"]),
    start_time, 
    dataset_license="CC-BY-4.0",
    # argv argument is optional, in real usage you can omit it
    argv=['example-cli'] + args,
    # current_user argument is optional, in real usage you can omit it
    current_user="someuser"
)

Will generate a `ro-crate-metadata.json` file in the current working directory describing the execution of the CLI command. (Click me to see crate content)

{
    "@context": [
        "https://w3id.org/ro/crate/1.1/context",
        "https://w3id.org/ro/terms/workflow-run/context"
    ],
    "@graph": [
        {
            "@id": "./",
            "@type": "Dataset",
            "conformsTo": {
                "@id": "https://w3id.org/ro/wfrun/process/0.5"
            },
            "datePublished": "2026-01-28T15:07:18.600135",
            "description": "An RO-Crate recording the files and directories that were used as input or output by example-cli.",
            "hasPart": [
                {
                    "@id": "input.txt"
                },
                {
                    "@id": "output.txt"
                }
            ],
            "license": "CC-BY-4.0",
            "name": "Files used by example-cli"
        },
        {
            "@id": "ro-crate-metadata.json",
            "@type": "CreativeWork",
            "about": {
                "@id": "./"
            },
            "conformsTo": {
                "@id": "https://w3id.org/ro/crate/1.1"
            }
        },
        {
            "@id": "https://w3id.org/ro/wfrun/process/0.5",
            "@type": "CreativeWork",
            "name": "Process Run Crate",
            "version": "0.5"
        },
        {
            "@id": "example-cli@1.2.3",
            "@type": "SoftwareApplication",
            "description": "Example CLI",
            "name": "example-cli",
            "version": "1.2.3"
        },
        {
            "@id": "input.txt",
            "@type": "File",
            "contentSize": 5,
            "description": "Input file",
            "encodingFormat": "text/plain",
            "name": "input.txt"
        },
        {
            "@id": "output.txt",
            "@type": "File",
            "contentSize": 5,
            "description": "Output file",
            "encodingFormat": "text/plain",
            "name": "output.txt"
        },
        {
            "@id": "someuser",
            "@type": "Person",
            "name": "someuser"
        },
        {
            "@id": "example-cli input.txt output.txt",
            "@type": "CreateAction",
            "agent": {
                "@id": "someuser"
            },
            "endTime": "2026-01-28T15:07:18.600135",
            "instrument": {
                "@id": "example-cli@1.2.3"
            },
            "name": "example-cli input.txt output.txt",
            "object": [
                {
                    "@id": "input.txt"
                }
            ],
            "result": [
                {
                    "@id": "output.txt"
                }
            ],
            "startTime": "2026-01-28T15:07:18.599714"
        }
    ]
}

You can also call the argument parser agnostic version of the recorder directly. (Click me to see code)

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\n")
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")

Example

See the example folder for a minimal example.

Contributions

See AGENTS.md for commands and hints for contributions.

Citation

See CITATION.cff for citation information.