flowrep 0.2.0__tar.gz → 0.3.0__tar.gz

{flowrep-0.2.0 → flowrep-0.3.0}/.gitignore

@@ -11,3 +11,4 @@ apidoc/
 .ipynb_checkpoints/
 test_times.dat
 core.*
+flowrep/_version.py

{flowrep-0.2.0 → flowrep-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowrep
-Version: 0.2.0
+Version: 0.3.0
 Summary: flowrep - Your premier tool for workflow representations
 Project-URL: Homepage, https://pyiron.org/
 Project-URL: Documentation, https://flowrep.readthedocs.io
@@ -49,6 +49,8 @@ Requires-Python: <3.14,>=3.11
 Requires-Dist: networkx<3.7.0,>=3.4.2
 Requires-Dist: pydantic<2.13.0,>=2.12.0
 Requires-Dist: pyiron-snippets<2.0.0,>=1.2.1
+Provides-Extra: notebooks
+Requires-Dist: numpy==2.4.2; extra == 'notebooks'
 Provides-Extra: pwd
 Requires-Dist: python-workflow-definition==0.1.4; extra == 'pwd'
 Description-Content-Type: text/markdown

{flowrep-0.2.0 → flowrep-0.3.0}/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/api/live.py

@@ -0,0 +1,9 @@
+"""
+Data classes for "live" stateful instance-views of the recipes.
+
+Intended to be a common export- and communication-format for WfMS of instance-views.
+Since they hold live, arbitrary python objects, they don't serialize trivially and are
+not (by themselves) a valid storage format.
+"""
+
+from flowrep.models.live import recipe2live as recipe2live

{flowrep-0.2.0 → flowrep-0.3.0}/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/api/schemas.py

@@ -1,8 +1,9 @@
 """
-Pydantic models, enums, and types used in constructing or inspecting recipe models.
+Pydantic models, types and classes, enums, and constants used in constructing or
+inspecting recipe models.
 
-Intended for power-users like workflow management system (WfMS) designers to work deeply
-with recipe objects in a structured, well-typed way.
+Primarily intended for power-users like workflow management system (WfMS) designers to
+work deeply with recipe objects in a structured, well-typed way.
 """
 
 from flowrep.models.base_models import RESERVED_NAMES as RESERVED_NAMES
@@ -17,9 +18,24 @@ from flowrep.models.edge_models import InputSource as InputSource
 from flowrep.models.edge_models import OutputTarget as OutputTarget
 from flowrep.models.edge_models import SourceHandle as SourceHandle
 from flowrep.models.edge_models import TargetHandle as TargetHandle
+from flowrep.models.live import NOT_DATA as NOT_DATA
+from flowrep.models.live import Atomic as Atomic
+from flowrep.models.live import Composite as Composite
+from flowrep.models.live import FlowControl as FlowControl
+from flowrep.models.live import InputPort as InputPort
+from flowrep.models.live import LiveNode as LiveNode
+from flowrep.models.live import NotData as NotData
+from flowrep.models.live import OutputPort as OutputPort
+from flowrep.models.live import Workflow as Workflow
+from flowrep.models.nodes.atomic_model import AtomicNode as AtomicNode
 from flowrep.models.nodes.atomic_model import UnpackMode as UnpackMode
+from flowrep.models.nodes.for_model import ForNode as ForNode
 from flowrep.models.nodes.helper_models import ConditionalCase as ConditionalCase
 from flowrep.models.nodes.helper_models import ExceptionCase as ExceptionCase
 from flowrep.models.nodes.helper_models import LabeledNode as LabeledNode
+from flowrep.models.nodes.if_model import IfNode as IfNode
+from flowrep.models.nodes.try_model import TryNode as TryNode
 from flowrep.models.nodes.union import Nodes as Nodes
 from flowrep.models.nodes.union import NodeType as NodeType
+from flowrep.models.nodes.while_model import WhileNode as WhileNode
+from flowrep.models.nodes.workflow_model import WorkflowNode as WorkflowNode

flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/api/wfms.py

@@ -0,0 +1,8 @@
+"""
+A toy Workflow Management System (WfMS) to convert recipes into live objects with
+output data.
+
+Intended for use in tests, and as an example for fully-fledged WfMS to refer to.
+"""
+
+from flowrep.models.wfms import run_recipe as run_recipe

flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/live.py

@@ -0,0 +1,303 @@
+"""
+Flowrep recipes represent a class-view of how data can be processed via a workflow.
+
+In this module, we provide a prototypical data structure for live, instance-view
+workflows, which can be mutated as they are executed to be enriched with data.
+
+Unlike the recipes, no goal is made to provide easy serialization, and these data
+structures natively hold complex python objects.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+import inspect
+import types
+from collections.abc import Callable, MutableMapping
+from typing import Any, get_args, get_origin, get_type_hints
+
+from pyiron_snippets import dotdict, retrieve, singleton
+
+from flowrep.models import base_models, edge_models
+from flowrep.models.nodes import (
+    atomic_model,
+    for_model,
+    if_model,
+    try_model,
+    union,
+    while_model,
+    workflow_model,
+)
+
+
+class NotData(metaclass=singleton.Singleton):
+    """
+    This class exists purely to initialize data channel values where no default value
+    is provided; it lets the channel know that it has _no data in it_ and thus should
+    not identify as ready.
+    """
+
+    @classmethod
+    def __repr__(cls):
+        # We use the class directly (not instances of it) where there is not yet data
+        # So give it a decent repr, even as just a class
+        return "NOT_DATA"
+
+    def __reduce__(self):
+        return "NOT_DATA"
+
+    def __bool__(self):
+        return False
+
+
+NOT_DATA = NotData()
+
+
+@dataclasses.dataclass(frozen=False)
+class _Port:
+    value: object | NotData = NOT_DATA
+    annotation: Any | None = None
+
+
+@dataclasses.dataclass(frozen=False)
+class InputPort(_Port):
+    default: object | NotData = NOT_DATA
+
+    def get_data(self) -> object | NotData:
+        """A shortcut for falling back on the default"""
+        return self.default if self.value is NOT_DATA else self.value
+
+
+@dataclasses.dataclass(frozen=False)
+class OutputPort(_Port): ...
+
+
+@dataclasses.dataclass(frozen=False)
+class LiveNode(abc.ABC):
+    recipe: union.NodeType
+    input_ports: MutableMapping[base_models.Label, InputPort]
+    output_ports: MutableMapping[base_models.Label, OutputPort]
+
+
+def recipe2live(recipe: union.NodeType) -> LiveNode:
+    match recipe:
+        case atomic_model.AtomicNode():
+            return Atomic.from_recipe(recipe)
+        case for_model.ForNode():
+            return FlowControl.from_recipe(recipe)
+        case if_model.IfNode():
+            return FlowControl.from_recipe(recipe)
+        case try_model.TryNode():
+            return FlowControl.from_recipe(recipe)
+        case while_model.WhileNode():
+            return FlowControl.from_recipe(recipe)
+        case workflow_model.WorkflowNode():
+            return Workflow.from_recipe(recipe)
+
+
+@dataclasses.dataclass(frozen=False)
+class Atomic(LiveNode):
+    function: Callable
+
+    @classmethod
+    def from_recipe(cls, recipe: atomic_model.AtomicNode) -> Atomic:
+        function, input_ports, output_ports = _parse_function(
+            recipe.reference.info.fully_qualified_name,
+            recipe.inputs,
+            recipe.outputs,
+            recipe.unpack_mode,
+        )
+        return Atomic(
+            recipe=recipe,
+            input_ports=dotdict.DotDict(input_ports),
+            output_ports=dotdict.DotDict(output_ports),
+            function=function,
+        )
+
+
+@dataclasses.dataclass(frozen=False)
+class Composite(LiveNode, abc.ABC):
+    nodes: MutableMapping[base_models.Label, LiveNode]
+    input_edges: edge_models.InputEdges
+    edges: edge_models.Edges
+    output_edges: edge_models.OutputEdges
+
+
+@dataclasses.dataclass(frozen=False)
+class Workflow(Composite):
+    @classmethod
+    def from_recipe(cls, recipe: workflow_model.WorkflowNode) -> Workflow:
+        if recipe.reference:
+            function, input_ports, output_ports = _parse_function(
+                recipe.reference.info.fully_qualified_name,
+                recipe.inputs,
+                recipe.outputs,
+            )
+        else:
+            input_ports = {label: InputPort() for label in recipe.inputs}
+            output_ports = {label: OutputPort() for label in recipe.outputs}
+        nodes = {label: recipe2live(child) for label, child in recipe.nodes.items()}
+        return Workflow(
+            recipe=recipe,
+            input_ports=dotdict.DotDict(input_ports),
+            output_ports=dotdict.DotDict(output_ports),
+            nodes=dotdict.DotDict(nodes),
+            input_edges=dict(recipe.input_edges),
+            edges=dict(recipe.edges),
+            output_edges=dict(recipe.output_edges),
+        )
+
+    # TODO: add/remove_node/edge/input/output methods, each guarded that they are
+    #   unavailable if the underlying recipe has a reference, and otherwise mutatiting
+    #   the underlying recipe at the same time
+
+
+@dataclasses.dataclass(frozen=False)
+class FlowControl(Composite):
+    @classmethod
+    def from_recipe(
+        cls,
+        recipe: (
+            for_model.ForNode
+            | if_model.IfNode
+            | try_model.TryNode
+            | while_model.WhileNode
+        ),
+    ) -> FlowControl:
+        """
+        Flow control nodes are composite with dynamic bodies; WfMS must populate the
+        nodes and edges at runtime according to recipe execution.
+        """
+        return FlowControl(
+            recipe=recipe,
+            input_ports=dotdict.DotDict(
+                {label: InputPort() for label in recipe.inputs}
+            ),
+            output_ports=dotdict.DotDict(
+                {label: OutputPort() for label in recipe.outputs}
+            ),
+            nodes=dotdict.DotDict(),
+            input_edges={},
+            edges={},
+            output_edges={},
+        )
+
+
+def _parse_function(
+    fully_qualified_name: str,
+    inputs: list[str],
+    outputs: list[str],
+    unpack_mode: atomic_model.UnpackMode = atomic_model.UnpackMode.TUPLE,
+) -> tuple[
+    types.FunctionType,
+    dict[base_models.Label, InputPort],
+    dict[base_models.Label, OutputPort],
+]:
+    function = retrieve.import_from_string(fully_qualified_name)
+    hints = get_type_hints(function, include_extras=True)
+    sig = inspect.signature(function)
+
+    # --- input ports ---
+    available = set(sig.parameters)
+    missing = set(inputs) - available
+    if missing:
+        raise ValueError(
+            f"Requested inputs {missing} not found in signature of {fully_qualified_name!r}"
+        )
+
+    input_ports: dict[str, InputPort] = {}
+    for name in inputs:
+        param = sig.parameters[name]
+        input_port = InputPort()
+        input_port.annotation = hints.get(name, None)
+        input_port.default = (
+            param.default if param.default is not inspect.Parameter.empty else NOT_DATA
+        )
+        input_ports[name] = input_port
+
+    # --- output ports ---
+    return_annotation = hints.get("return", None)
+    if unpack_mode == atomic_model.UnpackMode.NONE:
+        output_ports = _parse_return_without_unpacking(return_annotation, outputs)
+    elif unpack_mode == atomic_model.UnpackMode.TUPLE:
+        output_ports = _parse_return_tuple(return_annotation, outputs)
+    elif unpack_mode == atomic_model.UnpackMode.DATACLASS:
+        output_ports = _parse_return_dataclass(return_annotation, outputs)
+
+    return function, input_ports, output_ports
+
+
+def _parse_return_without_unpacking(
+    return_annotation, outputs: list[str]
+) -> dict[str, OutputPort]:
+    if len(outputs) != 1:  # pragma: no cover
+        raise ValueError(
+            f"Without return unpacking, only one output is allowed, but got {outputs}. "
+            f"This should have been caught by the underlying recipe validation. Please "
+            f"raise a GitHub issue reporting how you got here!"
+        )
+    return {outputs[0]: OutputPort(annotation=return_annotation)}
+
+
+def _parse_return_tuple(return_annotation, outputs: list[str]) -> dict[str, OutputPort]:
+    output_ports: dict[str, OutputPort]
+    if len(outputs) > 1:
+        origin = get_origin(return_annotation)
+        args = get_args(return_annotation)
+
+        if return_annotation is not None:
+            unpacking_hint = (
+                f"To collect the entire tuple in a single port use "
+                f"{atomic_model.UnpackMode.NONE} unpacking mode."
+            )
+
+            if origin is not tuple:
+                raise ValueError(
+                    f"Multiple outputs {outputs} requested but return annotation "
+                    f"{return_annotation!r} is not splittable -- only tuple return "
+                    f"hints are splittable. {unpacking_hint}"
+                )
+            if len(args) != len(outputs):
+                raise ValueError(
+                    f"Output labels {outputs} (n={len(outputs)}) do not match "
+                    f"length of return annotation {return_annotation} (n={len(args)}). "
+                    f"Tuple return hint unpacking requires one hint element per output."
+                    f" {unpacking_hint}"
+                )
+            output_ports = {
+                label: OutputPort(annotation=annotation)
+                for label, annotation in zip(outputs, args, strict=True)
+            }
+        else:
+            output_ports = {label: OutputPort() for label in outputs}
+    else:
+        output_ports = {outputs[0]: OutputPort(annotation=return_annotation)}
+    return output_ports
+
+
+def _parse_return_dataclass(
+    return_annotation, outputs: list[str]
+) -> dict[str, OutputPort]:
+    if not dataclasses.is_dataclass(return_annotation):  # pragma: no cover
+        raise TypeError(
+            f"Return annotation {return_annotation!r} is not a dataclass. This should "
+            f"have been caught by the underlying recipe validation. Please raise a "
+            f"GitHub issue reporting how you got here!"
+        )
+
+    fields = dataclasses.fields(return_annotation)
+    if len(outputs) != len(fields):  # pragma: no cover
+        raise ValueError(
+            f"Return dataclass {return_annotation!r} has {len(fields)} fields, "
+            f"{[f.name for f in fields]}, but {len(outputs)} outputs, {outputs} were "
+            f"requested. This should have been caught by the underlying recipe "
+            f"validation. Please raise a GitHub issue reporting how you got here!"
+        )
+
+    return {
+        label: OutputPort(
+            annotation=(field.type if field.type is not dataclasses.MISSING else None),
+        )
+        for label, field in zip(outputs, fields, strict=True)
+    }

{flowrep-0.2.0 → flowrep-0.3.0}/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/nodes/for_model.py

@@ -59,7 +59,12 @@ class ForNode(base_models.NodeModel):
         zipped_ports: The body node ports over which to do zipped iteration. Input
             edges will map parent input elements to each child node accordingly.
 
-    Note:
+    Notes:
+        At runtime, iterated input values should themselves be iterable. It is
+        recommended to pass values conforming to `collections.abc.Collection`. This is
+        a runtime behaviour, and is thus not enforced here at the recipe level in any
+        way.
+
         All iterated output — whether collected from body executions or forwarded from
         scattered inputs — should have the same length. Thus, forwarded inputs empower
         the node output to precisely provide which input was used to produce each

{flowrep-0.2.0 → flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages}/flowrep/models/parsers/atomic_parser.py

@@ -119,9 +119,10 @@ def parse_atomic(
     scraped_output_labels = _get_output_labels(func, unpack_mode)
     if len(output_labels) > 0 and len(output_labels) != len(scraped_output_labels):
         raise ValueError(
-            f"Explicitly provided output labels must match with function analysis and "
-            f"unpacking mode. Expected {len(scraped_output_labels)} output labels with "
-            f"unpacking mode '{unpack_mode}', got but got {output_labels}."
+            "Explicitly provided output labels must match the function analysis and "
+            f"unpack_mode: expected {len(scraped_output_labels)} labels for "
+            f"unpack_mode='{unpack_mode}', got {len(output_labels)} labels "
+            f"{output_labels}; inferred labels were {scraped_output_labels}."
         )
 
     return atomic_model.AtomicNode(

{flowrep-0.2.0 → flowrep-0.3.0}/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/parsers/dependency_parser.py

@@ -4,7 +4,7 @@ from collections.abc import Callable
 
 from pyiron_snippets import versions
 
-from flowrep.models.parsers import object_scope, parser_helpers
+from flowrep.models.parsers import import_parser, object_scope, parser_helpers
 
 CallDependencies = dict[versions.VersionInfo, Callable]
 
@@ -43,10 +43,13 @@ def get_call_dependencies(
         return call_dependencies
     visited.add(func_fqn)
 
-    scope = object_scope.get_scope(func)
     tree = parser_helpers.get_ast_function_node(func)
     collector = CallCollector()
     collector.visit(tree)
+    local_modules = import_parser.build_scope(collector.imports, collector.import_froms)
+    scope = object_scope.get_scope(func)
+    for name, obj in local_modules.items():
+        scope.register(name=name, obj=obj)
 
     for call in collector.calls:
         try:
@@ -105,7 +108,17 @@ def split_by_version_availability(
 class CallCollector(ast.NodeVisitor):
     def __init__(self):
         self.calls: list[ast.expr] = []
+        self.imports: list[ast.Import] = []
+        self.import_froms: list[ast.ImportFrom] = []
 
     def visit_Call(self, node: ast.Call) -> None:
         self.calls.append(node.func)
         self.generic_visit(node)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        self.imports.append(node)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        self.import_froms.append(node)
+        self.generic_visit(node)

flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages/flowrep/models/parsers/import_parser.py

@@ -0,0 +1,51 @@
+import ast
+import importlib
+
+from flowrep.models.parsers import object_scope
+from flowrep.models.parsers.object_scope import ScopeProxy
+
+
+def build_scope(
+    imports: list[ast.Import] | None = None,
+    import_froms: list[ast.ImportFrom] | None = None,
+) -> object_scope.ScopeProxy:
+    """
+    Build a scope dictionary from a list of `import` and `from ... import ...` statements.
+
+    Args:
+        imports (list | None): A list of `ast.Import` nodes.
+        import_froms (list | None): A list of `ast.ImportFrom` nodes.
+
+    Returns:
+        object_scope.ScopeProxy: A mutable mapping representing the scope with imported
+            modules and objects.
+    """
+    scope = ScopeProxy()
+
+    imports = imports or []
+    import_froms = import_froms or []
+
+    # Handle `import` statements
+    for imp in imports:
+        for alias in imp.names:
+            asname = alias.asname or alias.name
+            module = importlib.import_module(alias.name)
+            scope.register(name=asname, obj=module)
+
+    # Handle `from ... import ...` statements
+    for imp_from in import_froms:
+        level = imp_from.level
+        # Dynamically import the module (absolute or relative)
+        if imp_from.module is None or level > 0:
+            raise ValueError(
+                f"Relative imports are not supported in dependency parsing. "
+                f"Encountered importing from {imp_from.module}."
+            )
+        module = importlib.import_module(imp_from.module)
+        for alias in imp_from.names:
+            name = alias.name
+            asname = alias.asname or name
+            obj = getattr(module, name)
+            scope.register(name=asname, obj=obj)
+
+    return scope

{flowrep-0.2.0 → flowrep-0.3.0/cached-miniforge/my-env/lib/python3.1/site-packages}/flowrep/models/parsers/object_scope.py

@@ -3,24 +3,63 @@ from __future__ import annotations
 import ast
 import builtins
 import inspect
-from types import FunctionType
+import sys
+from collections.abc import Callable, MutableMapping
+from typing import Any
 
 
-class ScopeProxy:
+class _EmptyValue: ...
+
+
+class ScopeProxy(MutableMapping[str, object]):
     """
-    Make the __dict__-like scope dot-accessible without duplicating the dictionary
-    like types.SimpleNamespace would.
+    A mutable mapping to connect symbols to python objects.
+
+    By default, does not allow re-registration of existing symbols to new values.
     """
 
-    def __init__(self, d: dict):
-        self._d = d
+    def __init__(
+        self,
+        d: MutableMapping[str, object] | None = None,
+        allow_overwrite: bool = False,
+    ):
+        self._d = {} if d is None else {k: v for k, v in d.items()}
+        self.allow_overwrite = allow_overwrite
+
+    def __getitem__(self, name: str):
+        return self._d[name]
+
+    def __setitem__(self, name: str, value: object):
+        if not self.allow_overwrite:
+            old_value = self._d.get(name, _EmptyValue)
+            if old_value is not _EmptyValue and value is not old_value:
+                raise ValueError(
+                    f"Variable {name} already exists as {old_value!r} in this "
+                    f"scope. It cannot be reassigned to a new value of {value!r} "
+                    f"while allow_overwrite is False."
+                )
+            self._d[name] = value
+        else:
+            self._d[name] = value
+
+    def __delitem__(self, name: str):
+        self._d.__delitem__(name)
+
+    def __iter__(self):
+        return iter(self._d)
+
+    def __len__(self):
+        return len(self._d)
 
     def __getattr__(self, name: str):
         try:
-            return self._d[name]
+            return self.__getitem__(name)
         except KeyError:
             raise AttributeError(name) from None
 
+    def __str__(self):
+        return str(self._d)
+
     def register(self, name: str, obj: object) -> None:
         """
         Add a name → object binding to this scope.
@@ -30,7 +69,7 @@ class ScopeProxy:
         resolutions within this scope (or any scope that shares the same
         backing namespace).
         """
-        self._d[name] = obj
+        self[name] = obj
 
     def fork(self) -> ScopeProxy:
         """
@@ -40,11 +79,22 @@ class ScopeProxy:
         affect the parent.  Used when walking conditional branches so that
         branch-local imports don't leak into sibling branches.
         """
-        return ScopeProxy(dict(self._d))
-
-
-def get_scope(func: FunctionType) -> ScopeProxy:
-    return ScopeProxy(inspect.getmodule(func).__dict__ | vars(builtins))
+        return ScopeProxy(self, allow_overwrite=self.allow_overwrite)
+
+
+def get_scope(func: Callable[..., Any] | type[Any]) -> ScopeProxy:
+    module = inspect.getmodule(func)
+    if module is None:
+        module_name = getattr(func, "__module__", None)
+        if module_name is not None:
+            module = sys.modules.get(module_name)
+    if module is None:
+        raise ValueError(
+            f"Cannot determine the module for {func!r}. "
+            "inspect.getmodule() returned None and no resolvable __module__ "
+            "attribute was found."
+        )
+    return ScopeProxy(module.__dict__ | vars(builtins))
 
 
 def resolve_attribute_to_object(attribute: str, scope: ScopeProxy | object) -> object: