rocrate-action-recorder

Python package to record calls of Python CLI commands into a Research Object Crate (RO-Crate). Useful to track which commands were executed, which files were used as input or output, and which software was used to execute the command.

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

Provides adapters for CLIs based on:

• argparse example usage docs homepage
• click example usage docs homepage
• cyclopts example usage docs homepage

Install

pip install rocrate-action-recorder

For Click support, install the optional extra:

pip install "rocrate-action-recorder[click]"

For Cyclopts support, install the optional extra:

pip install "rocrate-action-recorder[cyclopts]"

Usage

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

import argparse
from pathlib import Path
import sys

from rocrate_action_recorder import recorded_argparse

parser = argparse.ArgumentParser(prog="example-cli", description="Example CLI")
parser.add_argument("--version", action="version", version="%(prog)s 1.2.3")
parser.add_argument("--no-record", action="store_false", help="Disable RO-Crate recording.")
parser.add_argument("input", type=Path, help="Input file")
parser.add_argument("output", type=Path, help="Output file")


@recorded_argparse(
    parser=parser,
    input_files=["input"],
    output_files=["output"],
    dataset_license="CC-BY-4.0",
    enabled_argument="no_record",
)
def handler(args: argparse.Namespace):
    # For demonstration, just upper case input to output, replace with real logic
    args.output.write_text(args.input.read_text().upper())


# Prepare input
Path("input.txt").write_text("hello")
# Simulate command-line arguments
sys.argv.extend(["input.txt", "output.txt"])

args = parser.parse_args()
handler(args)

After execution, a ro-crate-metadata.json file (like this one) will be generated in the current working directory, describing the execution of the CLI command.

You can also call the low-level record function directly.

See documentation for more details.

Contributions

See AGENTS.md for commands and hints for contributions.

Citation

See CITATION.cff for citation information.