rocrate_action_recorder.adapters.argparse¶

Adapter for argparse CLI framework.

Attributes¶

logger

Exceptions¶

MissingDestArgparseSubparserError

Raised when an argparse subparser is missing the 'dest' argument.

Functions¶

`argparse_help`(→ str \| None)	Get help text for an argparse argument.
`argparse_value2paths`(→ list[pathlib.Path])	Convert an argparse value to a list of Path objects.
`try_convert_to_path`(→ pathlib.Path \| None)	Try to convert a single item to a Path.
`version_from_parser`(→ str \| None)	Attempt to extract version information from an ArgumentParser version action.
`program_from_parser`(→ rocrate_action_recorder.core.Program)	Extract Program information from argparse parser and namespace.
`map_name2paths`(...)
`map_names2paths`(...)
`collect_record_info_from_argparse`(...)	Collect Program and IOArgumentPaths from argparse so it can be recorded as an action in RO-Crate.
`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.

Module Contents¶

rocrate_action_recorder.adapters.argparse.logger¶

exception rocrate_action_recorder.adapters.argparse.MissingDestArgparseSubparserError[source]¶

Bases: ValueError

Raised when an argparse subparser is missing the ‘dest’ argument.

rocrate_action_recorder.adapters.argparse.argparse_help(parser: argparse.ArgumentParser, ns: argparse.Namespace, arg_name: str) → str | None[source]¶

Get help text for an argparse argument.

Parameters:

parser – The ArgumentParser instance.
ns – The parsed Namespace from argparse.
arg_name – The argument destination name.

Returns:

The help text if found, otherwise None.

rocrate_action_recorder.adapters.argparse.argparse_value2paths(v: Any) → list[pathlib.Path][source]¶

Convert an argparse value to a list of Path objects.

Handles single paths, file-like objects, and lists/tuples of paths. Deduplicates paths before returning.

Parameters:: v – The value from argparse arguments.
Returns:: A list of deduplicated Path objects. Empty list if value is not path-like.

rocrate_action_recorder.adapters.argparse.try_convert_to_path(item: Any) → pathlib.Path | None[source]¶: Try to convert a single item to a Path.

rocrate_action_recorder.adapters.argparse.version_from_parser(parser: argparse.ArgumentParser) → str | None[source]¶

Attempt to extract version information from an ArgumentParser version action.

Parameters:: parser – The ArgumentParser instance.
Returns:: The version string if found, otherwise None.

Example

>>> import argparse
>>> from rocrate_action_recorder.adapters.argparse import version_from_parser
>>>
>>> parser = argparse.ArgumentParser(prog="example-cli")
>>> _ = parser.add_argument('--version', action='version', version='1.2.3')
>>>
>>> version_from_parser(parser)
'1.2.3'

rocrate_action_recorder.adapters.argparse.program_from_parser(parser: argparse.ArgumentParser, ns: argparse.Namespace) → rocrate_action_recorder.core.Program[source]¶

Extract Program information from argparse parser and namespace.

Parameters:

parser – The ArgumentParser instance.
ns – The parsed Namespace from argparse.

Returns:

A Program object with details about the CLI program.

rocrate_action_recorder.adapters.argparse.map_name2paths(parser: argparse.ArgumentParser, ns: argparse.Namespace, name: str) → list[rocrate_action_recorder.core.IOArgumentPath][source]¶

rocrate_action_recorder.adapters.argparse.map_names2paths(parser: argparse.ArgumentParser, ns: argparse.Namespace, names: list[str]) → list[rocrate_action_recorder.core.IOArgumentPath][source]¶

rocrate_action_recorder.adapters.argparse.collect_record_info_from_argparse(parser: argparse.ArgumentParser, ns: argparse.Namespace, ios: rocrate_action_recorder.adapters.shared.IOArgumentNames, software_version: str | None = None) → tuple[rocrate_action_recorder.core.Program, rocrate_action_recorder.core.IOArgumentPaths][source]¶

Collect Program and IOArgumentPaths from argparse so it can be recorded as an action in RO-Crate.

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.

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.
software_version – Optional version string to override detected version.

Returns:

A tuple of (Program, IOArgumentPaths).

rocrate_action_recorder.adapters.argparse.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

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.adapters.argparse.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.