m3resp.register_step

m3resp.register_step(name, *, reads=None, optional_reads=(), writes=(), replaces=(), requires=(), summary='', description='', parameters=(), parameters_reviewed=False, mutually_exclusive_parameters=(), input_artifacts=(), output_artifacts=(), session_reads=(), session_writes=(), modality=None, category=None, alternatives=(), optional_packages=(), resource_profile=None, version=None, deprecated_since=None, record=False, aliases=())

Register a function and its workflow inputs, outputs and descriptions.

Parameters:

• name (str) – Operation name in lowercase prefix.operation form.

• reads (Mapping[str, str | None] | None) – Function arguments mapped to default context keys. None values require explicit input bindings in the spec.

• optional_reads (tuple[str, ...]) – Names from reads that may be absent at execution time.

• writes (tuple[str, ...]) – Output names returned by the step, renameable through out:.

• replaces (tuple[str, ...]) – Names from writes whose value replaces the value an earlier step wrote under the same context key.

• requires (tuple[str, ...]) – Additional context keys required before execution.

• summary (str) – Short description; defaults to the function docstring’s first line.

• description (str) – Longer description for step discovery.

• parameters (tuple[StepParameter, ...]) – Static parameter descriptions, including units and limits.

• parameters_reviewed (bool) – Whether an empty parameter list is confirmed complete. Set to True automatically when parameter descriptions are supplied.

• mutually_exclusive_parameters (tuple[tuple[str, ...], ...]) – Groups with at most one setting per invocation.

• input_artifacts (tuple[StepArtifact, ...]) – Descriptions of values read by the step.

• output_artifacts (tuple[StepArtifact, ...]) – Descriptions of values returned by the step.

• session_reads (tuple[str, ...]) – Dotted names of session resources read directly.

• session_writes (tuple[str, ...]) – Dotted names of session resources changed directly.

• modality (str | None) – Device or technique associated with the step.

• category (str | None) – Processing or measurement category.

• alternatives (tuple[str, ...]) – Names of related operations.

• optional_packages (tuple[str, ...]) – Package names used to report availability.

• resource_profile (str | None) – Optional description of processing resources needed.

• version (str | None) – Optional operation version.

• deprecated_since (str | None) – Version from which this operation is deprecated.

• record (bool) – Add one provenance record to session.provenance after each call. The record holds the step name, its reads and writes, the installed version of its first optional package (None for a step without one), and the details the step returns under the output key "_provenance". That key is removed from the outputs. The step must read session.

• aliases (tuple[str, ...]) – Former operation names that resolve to this registration and are omitted from step discovery.

Returns:

Decorator that validates metadata, adds the definition and

aliases to the registries, and returns the supplied function, or with record=True the function wrapped to record each call.

Return type:

Callable

Raises:

• ValueError – When applying the decorator, if a name or alias conflicts with a registration, optional_reads names an undeclared input, or replaces names an undeclared output.

• StepMetadataError – When applying the decorator, if names, parameters, input/output descriptions or their JSON representation are invalid, or record=True is set for a step that does not read session.