flowrep.parsers.atomic_parser module

flowrep.parsers.atomic_parser.atomic(func: _AtomicTarget, /) → _AtomicTarget

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

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 a single value is provided, forces the node to have a single output port (i.e. tuple returns are provided _as_ tuples); when multiple are provided, their count must match the number of outputs inferred from the function.

• 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 | type, *output_labels: str, 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 absent, output ports are inferred from available returns; when a single label is provided, exactly one output port will be produced regardless of return values (i.e. returning tuple returns _as_ a tuple); when multiple labels are provided, their count is compared against the count scraped from the function itself.

• 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.