flowrep.parsers.atomic_parser module

flowrep.parsers.atomic_parser.atomic(func: LambdaType | str | None = None, /, *output_labels: str, unpack_mode: UnpackMode = UnpackMode.TUPLE, version_scraping: dict[str, Callable[[str], str | None]] | None = None, forbid_main: bool = False, forbid_locals: bool = False, require_version: bool = False) → LambdaType | Callable[[LambdaType], LambdaType]

Decorator that attaches a AtomicRecipe to the flowrep_recipe attribute of a function.

The decorated function’s module, qualname, and (optionally) package version are captured as provenance metadata via of().

Can be used with or without arguments.

Parameters:

• func – The function to decorate. Passed positionally by Python when the decorator is used without parentheses.

• *output_labels – Explicit names for the node’s output ports. When provided, their count must match the number of outputs inferred from the function and the chosen unpack_mode.

• unpack_mode – How to convert the function’s return value into output ports. See UnpackMode.

• version_scraping – Optional mapping from top-level package names to callables that return a version string, for packages that don’t expose __version__. Forwarded to of().

• forbid_main – If True, raise if the function’s module is __main__.

• forbid_locals – If True, raise if the function’s qualname contains <locals> (i.e. it was defined inside another function).

• require_version – If True, raise if no version can be determined for the function’s package.

Returns:

The original function with a flowrep_recipe attribute holding an AtomicRecipe.

flowrep.parsers.atomic_parser.get_labeled_recipe(ast_call: Call, existing_names: Iterable[str], scope: ScopeProxy, info_factory: VersionInfoFactory) → LabeledRecipe

flowrep.parsers.atomic_parser.parse_atomic(func: LambdaType, *output_labels: str, unpack_mode: UnpackMode = UnpackMode.TUPLE, version_scraping: dict[str, Callable[[str], str | None]] | None = None, forbid_main: bool = False, forbid_locals: bool = False, require_version: bool = False) → AtomicRecipe

Build an AtomicRecipe from a plain Python function.

Introspects the function to determine its fully qualified name, package version, input parameter names, and output port names (via AST return-value analysis and/or type annotations).

Parameters:

• func – The function to represent as an atomic node.

• *output_labels – Explicit output port names. When provided, their count must match the number of outputs inferred from the function and the chosen unpack_mode.

• unpack_mode – How to convert the function’s return value into output ports.

• version_scraping – Optional version-scraping overrides, forwarded to of().

• forbid_main – If True, raise if the function’s module is __main__.

• forbid_locals – If True, raise if the function’s qualname contains <locals>.

• require_version – If True, raise if no version can be determined.

Returns:

A fully constructed AtomicRecipe.

Raises:

ValueError – If output_labels length mismatches the inferred output count, or if any forbid_* / require_* constraint is violated.