flowrep 0.5.0__tar.gz → 0.5.1__tar.gz

{flowrep-0.5.0 → flowrep-0.5.1}/.gitignore

@@ -11,6 +11,6 @@ _build/
 apidoc/
 .ipynb_checkpoints/
 test_times.dat
-CLAUD.md
+CLAUDE.md
 core.*
 src/flowrep/_version.py

{flowrep-0.5.0 → flowrep-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowrep
-Version: 0.5.0
+Version: 0.5.1
 Summary: flowrep - Your premier tool for workflow representations
 Project-URL: Homepage, https://pyiron.org/
 Project-URL: Documentation, https://flowrep.readthedocs.io
@@ -48,15 +48,15 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: <3.15,>=3.11
 Requires-Dist: pydantic<2.13.0,>=2.12.0
-Requires-Dist: pyiron-snippets<2.0.0,>=1.2.1
+Requires-Dist: pyiron-snippets<2.0.0,>=1.3.0
 Provides-Extra: notebooks
 Requires-Dist: numpy==2.4.6; extra == 'notebooks'
 Provides-Extra: pwd
 Requires-Dist: python-workflow-definition==0.1.5; extra == 'pwd'
 Provides-Extra: storage
-Requires-Dist: bagofholding==0.1.11; extra == 'storage'
+Requires-Dist: bagofholding==0.1.12; extra == 'storage'
 Provides-Extra: storage-widget
-Requires-Dist: bagofholding==0.1.11; extra == 'storage-widget'
+Requires-Dist: bagofholding==0.1.12; extra == 'storage-widget'
 Requires-Dist: ipytree==0.2.2; extra == 'storage-widget'
 Description-Content-Type: text/markdown
 
@@ -213,6 +213,8 @@ run-time, but their IO signature is always fully known a priori.
 **Clear separation.** Of prospective, "class view" recipes, and retrospective, 
 "instance view" data objects.
 
+**Convertable and compatible.** Recipes can be compiled back to python functions, and converted from [`python-workflow-definition`](https://github.com/pythonworkflow/python-workflow-definition/) recipes (also _to_ PWD, where recipe operations are the subset supported by the PWD framework).
+
 ### Example: flow control and nesting
 
 So far we've seen `"workflow"` nodes, and alluded to `"atomic"` nodes.
@@ -315,20 +317,16 @@ these underlying functions when we run the recipe with a WfMS.
 
 Recipes are *prospective* — they describe a computation template without holding
 data. For retrospective analysis (inspecting what actually happened during a
-run), flowrep provides two additional layers accessible through the API:
-
-```python
->>> from flowrep.api import tools as frt
-
-```
+run), flowrep provides two additional layers accessible through the `tools` and 
+`schemas` submodules of the API.
 
-**`flowrep.api.tools.recipe2data`** converts a recipe from the prospective "class view"
+**`flowrep.tools.recipe2data`** converts a recipe from the prospective "class view"
 to the retrospective "instance view" — a mutable data structure whose input and output 
 ports can hold actual Python values. Retrospective data objects mirror the recipe graph
 but trade JSON-serializability for the ability to carry arbitrary data:
 
 ```python
->>> wf_data = frt.recipe2data(double_and_add.flowrep_recipe)
+>>> wf_data = fr.tools.recipe2data(double_and_add.flowrep_recipe)
 
 ```
 
@@ -338,7 +336,7 @@ by a minimal, built-in WfMS intended as a reference implementation and for use
 in tests and documentation (like this!):
 
 ```python
->>> retrospective = frt.run_recipe(
+>>> retrospective = fr.tools.run_recipe(
 ...     double_and_add.flowrep_recipe, a=3, b=100, target=40
 ... )
 >>> retrospective.output_ports["result"].value

{flowrep-0.5.0 → flowrep-0.5.1}/docs/README.md

@@ -151,6 +151,8 @@ run-time, but their IO signature is always fully known a priori.
 **Clear separation.** Of prospective, "class view" recipes, and retrospective, 
 "instance view" data objects.
 
+**Convertable and compatible.** Recipes can be compiled back to python functions, and converted from [`python-workflow-definition`](https://github.com/pythonworkflow/python-workflow-definition/) recipes (also _to_ PWD, where recipe operations are the subset supported by the PWD framework).
+
 ### Example: flow control and nesting
 
 So far we've seen `"workflow"` nodes, and alluded to `"atomic"` nodes.
@@ -253,20 +255,16 @@ these underlying functions when we run the recipe with a WfMS.
 
 Recipes are *prospective* — they describe a computation template without holding
 data. For retrospective analysis (inspecting what actually happened during a
-run), flowrep provides two additional layers accessible through the API:
-
-```python
->>> from flowrep.api import tools as frt
-
-```
+run), flowrep provides two additional layers accessible through the `tools` and 
+`schemas` submodules of the API.
 
-**`flowrep.api.tools.recipe2data`** converts a recipe from the prospective "class view"
+**`flowrep.tools.recipe2data`** converts a recipe from the prospective "class view"
 to the retrospective "instance view" — a mutable data structure whose input and output 
 ports can hold actual Python values. Retrospective data objects mirror the recipe graph
 but trade JSON-serializability for the ability to carry arbitrary data:
 
 ```python
->>> wf_data = frt.recipe2data(double_and_add.flowrep_recipe)
+>>> wf_data = fr.tools.recipe2data(double_and_add.flowrep_recipe)
 
 ```
 
@@ -276,7 +274,7 @@ by a minimal, built-in WfMS intended as a reference implementation and for use
 in tests and documentation (like this!):
 
 ```python
->>> retrospective = frt.run_recipe(
+>>> retrospective = fr.tools.run_recipe(
 ...     double_and_add.flowrep_recipe, a=3, b=100, target=40
 ... )
 >>> retrospective.output_ports["result"].value

{flowrep-0.5.0 → flowrep-0.5.1}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = [ "hatchling==1.29.0", "hatch-vcs==0.5.0",]
+requires = [ "hatchling==1.30.1", "hatch-vcs==0.5.0",]
 build-backend = "hatchling.build"
 
 [project]
@@ -9,7 +9,7 @@ readme = "docs/README.md"
 keywords = [ "pyiron",]
 requires-python = ">=3.11, <3.15"
 classifiers = [ "Development Status :: 4 - Beta", "Topic :: Scientific/Engineering", "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", "Operating System :: OS Independent", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14",]
-dependencies = [ "pydantic>=2.12.0,<2.13.0", "pyiron_snippets>=1.2.1,<2.0.0",]
+dependencies = [ "pydantic>=2.12.0,<2.13.0", "pyiron_snippets>=1.3.0,<2.0.0",]
 dynamic = [ "version",]
 [[project.authors]]
 name = "Sam Waseda"
@@ -30,7 +30,7 @@ Repository = "https://github.com/pyiron/flowrep"
 [project.optional-dependencies]
 pwd = [ "python-workflow-definition==0.1.5",]
 notebooks = [ "numpy==2.4.6",]
-storage = [ "bagofholding==0.1.11",]
+storage = [ "bagofholding==0.1.12",]
 storage-widget = [ "flowrep[storage]", "ipytree==0.2.2",]
 
 [tool.ruff]

{flowrep-0.5.0 → flowrep-0.5.1}/src/flowrep/__init__.py

@@ -6,10 +6,12 @@ attribute onto a function at definition time, and parsers (`parse_atomic`,
 
 import importlib.metadata
 
-from flowrep.api.tools import atomic as atomic
-from flowrep.api.tools import parse_atomic as parse_atomic
-from flowrep.api.tools import parse_workflow as parse_workflow
-from flowrep.api.tools import workflow as workflow
+from flowrep.api import atomic as atomic
+from flowrep.api import parse_atomic as parse_atomic
+from flowrep.api import parse_workflow as parse_workflow
+from flowrep.api import schemas as schemas
+from flowrep.api import tools as tools
+from flowrep.api import workflow as workflow
 
 try:
     # Installed package will find its version

{flowrep-0.5.0 → flowrep-0.5.1}/src/flowrep/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.0'
-__version_tuple__ = version_tuple = (0, 5, 0)
+__version__ = version = '0.5.1'
+__version_tuple__ = version_tuple = (0, 5, 1)
 
 __commit_id__ = commit_id = None

flowrep-0.5.1/src/flowrep/api/__init__.py

@@ -0,0 +1,15 @@
+"""
+The public interface for flowrep, protected by semver
+
+The most fundamental user tools (parsing and decorating) are provided here at the top
+level, while other resources are nested by category as tools or schemas. The shorter
+tools list is likely to be useful for all power users, while schemas are intended to
+primarily benefit downstream developers (e.g. WfMS creators).
+"""
+
+from flowrep.api import schemas as schemas
+from flowrep.api import tools as tools
+from flowrep.api.tools import atomic as atomic
+from flowrep.api.tools import parse_atomic as parse_atomic
+from flowrep.api.tools import parse_workflow as parse_workflow
+from flowrep.api.tools import workflow as workflow

flowrep-0.5.1/src/flowrep/api/schemas.py

@@ -0,0 +1,51 @@
+"""
+Pydantic models, types and classes, enums, and constants used in constructing or
+inspecting recipe models.
+
+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.base_models import RESERVED_NAMES as RESERVED_NAMES
+from flowrep.base_models import Label as Label
+from flowrep.base_models import Labels as Labels
+from flowrep.base_models import NodeRecipe as NodeRecipe
+from flowrep.base_models import PythonReference as PythonReference
+from flowrep.base_models import RecipeElementType as RecipeElementType
+from flowrep.base_models import RestrictedParamKind as RestrictedParamKind
+from flowrep.compiler.source import RenderedSource as RenderedSource
+from flowrep.edge_models import Edges as Edges
+from flowrep.edge_models import InputEdges as InputEdges
+from flowrep.edge_models import InputSource as InputSource
+from flowrep.edge_models import OutputEdges as OutputEdges
+from flowrep.edge_models import OutputTarget as OutputTarget
+from flowrep.edge_models import SourceHandle as SourceHandle
+from flowrep.edge_models import TargetHandle as TargetHandle
+from flowrep.prospective.atomic_recipe import AtomicRecipe as AtomicRecipe
+from flowrep.prospective.atomic_recipe import UnpackMode as UnpackMode
+from flowrep.prospective.for_recipe import ForEachRecipe as ForEachRecipe
+from flowrep.prospective.helper_models import ConditionalCase as ConditionalCase
+from flowrep.prospective.helper_models import ExceptionCase as ExceptionCase
+from flowrep.prospective.helper_models import LabeledRecipe as LabeledRecipe
+from flowrep.prospective.if_recipe import IfRecipe as IfRecipe
+from flowrep.prospective.try_recipe import TryRecipe as TryRecipe
+from flowrep.prospective.union_types import RecipeDiscrimination as RecipeDiscrimination
+from flowrep.prospective.union_types import Recipes as Recipes
+from flowrep.prospective.while_recipe import WhileRecipe as WhileRecipe
+from flowrep.prospective.workflow_recipe import WorkflowRecipe as WorkflowRecipe
+from flowrep.retrospective.datastructures import NOT_DATA as NOT_DATA
+from flowrep.retrospective.datastructures import AtomicData as AtomicData
+from flowrep.retrospective.datastructures import CompositeData as CompositeData
+from flowrep.retrospective.datastructures import DagData as DagData
+from flowrep.retrospective.datastructures import FlowControlData as FlowControlData
+from flowrep.retrospective.datastructures import ForEachData as ForEachData
+from flowrep.retrospective.datastructures import IfData as IfData
+from flowrep.retrospective.datastructures import InputDataPort as InputDataPort
+from flowrep.retrospective.datastructures import InputDataPorts as InputDataPorts
+from flowrep.retrospective.datastructures import NodeData as NodeData
+from flowrep.retrospective.datastructures import NotData as NotData
+from flowrep.retrospective.datastructures import OutputDataPort as OutputDataPort
+from flowrep.retrospective.datastructures import OutputDataPorts as OutputDataPorts
+from flowrep.retrospective.datastructures import TryData as TryData
+from flowrep.retrospective.datastructures import WhileData as WhileData
+from flowrep.subgraph_validation import ProspectiveOutputEdges as ProspectiveOutputEdges

flowrep-0.5.1/src/flowrep/api/tools.py

@@ -0,0 +1,17 @@
+"""
+Functions for creating and transforming flowrep data.
+
+Intended for users who want to go beyond the simple parsers and decorators, as well as
+for downstream library developers.
+"""
+
+from flowrep.compiler.source import flowrep2python as flowrep2python
+from flowrep.converters.python_workflow_definition import flowrep2pwd as flowrep2pwd
+from flowrep.converters.python_workflow_definition import pwd2flowrep as pwd2flowrep
+from flowrep.parsers.atomic_parser import atomic as atomic
+from flowrep.parsers.atomic_parser import parse_atomic as parse_atomic
+from flowrep.parsers.workflow_parser import parse_workflow as parse_workflow
+from flowrep.parsers.workflow_parser import workflow as workflow
+from flowrep.retrospective.datastructures import recipe2data as recipe2data
+from flowrep.retrospective.storage import LexicalBagBrowser as LexicalBagBrowser
+from flowrep.wfms import run_recipe as run_recipe

flowrep-0.5.1/src/flowrep/compiler/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module handles the reverse transformation of flowrep objects back to python whence
+they can be parsed.
+"""

flowrep-0.5.1/src/flowrep/compiler/annotate.py

@@ -0,0 +1,141 @@
+"""Render Python defaults and annotations into self-contained source text.
+
+Each helper produces candidate source text and then verifies that the text
+reconstructs the original object (render-then-verify). On any failure it returns
+``None`` so the caller can fall back to binding the live object into a namespace.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import importlib
+import types
+import typing
+from typing import Any
+
+from pyiron_snippets import versions
+
+_ANNOTATED_ORIGIN_SENTINEL = typing.get_origin(typing.Annotated[int, "x"])
+
+
+def render_annotation(ann: Any, imports: set[str]) -> str | None:
+    """Return verified source text for an annotation, or ``None``.
+
+    Mutates ``imports`` with the bare module name for every non-builtin module
+    the text references. Returns ``None`` (without leaving partial imports
+    behind) when any part of the annotation cannot be rendered or the rendered
+    text fails to evaluate back to an equal object.
+    """
+    local_imports: set[str] = set()
+    text = _render(ann, local_imports)
+    if text is None:
+        return None
+    if text == "None":  # None / NoneType both legal and normalized by get_type_hints
+        return "None"
+    if not _verifies(text, ann, local_imports):  # pragma: no cover - defensive
+        return None
+    imports.update(local_imports)
+    return text
+
+
+def _render(ann: Any, imports: set[str]) -> str | None:
+    if ann is None or ann is type(None):
+        return "None"
+
+    origin = typing.get_origin(ann)
+    if origin is not None:
+        return _render_subscripted(ann, origin, imports)
+
+    if isinstance(ann, type):
+        return _render_plain_type(ann, imports)
+    return None
+
+
+def _render_subscripted(ann: Any, origin: Any, imports: set[str]) -> str | None:
+    args = typing.get_args(ann)
+
+    # Union / Optional: render members joined by ` | `. typing.Union[...] has
+    # origin typing.Union; the PEP 604 `int | str` form has origin
+    # types.UnionType. Both compare equal after eval, so render both as `A | B`.
+    if origin is typing.Union or origin is types.UnionType:
+        rendered = [_render(a, imports) for a in args]
+        if any(part is None for part in rendered):
+            return None
+        return " | ".join(part for part in rendered if part is not None)
+
+    # Annotated[T, *meta]: base via _render, metadata via render_default first
+    # (literals) then _render (types).
+    if origin is _ANNOTATED_ORIGIN_SENTINEL:
+        base = _render(args[0], imports)
+        if base is None:
+            return None
+        meta_texts = []
+        for meta in args[1:]:
+            meta_text = render_default(meta)
+            if meta_text is None:
+                meta_text = _render(meta, imports)
+            if meta_text is None:
+                return None
+            meta_texts.append(meta_text)
+        return f"typing.Annotated[{', '.join([base, *meta_texts])}]"
+
+    # Literal[...]: every arg must be a literal value.
+    if origin is typing.Literal:
+        arg_texts = [render_default(a) for a in args]
+        if any(part is None for part in arg_texts):
+            return None
+        return f"typing.Literal[{', '.join(part for part in arg_texts if part)}]"
+
+    # Generic alias over a real origin type (list[int], dict[str, int], ...).
+    if isinstance(origin, type):
+        origin_text = _render_plain_type(origin, imports)
+        if origin_text is None:
+            return None
+        arg_texts = [_render(a, imports) for a in args]
+        if any(part is None for part in arg_texts):
+            return None
+        return f"{origin_text}[{', '.join(part for part in arg_texts if part)}]"
+
+    return None
+
+
+def _render_plain_type(ann: type, imports: set[str]) -> str | None:
+    info = versions.VersionInfo.of(ann)
+    if info.is_local or info.is_lambda or info.in_main:
+        return None
+    if info.module != "builtins":
+        imports.add(info.module)
+    return info.findable_at
+
+
+def _verifies(text: str, ann: Any, imports: set[str]) -> bool:
+    namespace: dict[str, Any] = {"__builtins__": builtins}
+    namespace["typing"] = importlib.import_module("typing")
+    for line in imports:
+        top = line.split(".")[0]
+        namespace[top] = importlib.import_module(top)
+    try:
+        evaluated = eval(text, namespace)  # noqa: S307 - controlled codegen text
+    except Exception:  # noqa: BLE001  # pragma: no cover - defensive verify net
+        return False
+    return evaluated == ann or evaluated is ann
+
+
+def render_default(value: Any) -> str | None:
+    """Return source text for a *literal* default, or ``None``.
+
+    The text is accepted only when ``ast.literal_eval`` reproduces a value equal
+    to (and of the same type as) the input. This covers ints, floats, strs,
+    bytes, bools, ``None``, and nested tuple/list/dict/set of these, and rejects
+    sentinels, enums, ``nan``, ``frozenset`` (no literal syntax), and arbitrary
+    instances. No imports are required for any accepted value.
+    """
+    try:
+        text = repr(value)
+        parsed = ast.literal_eval(text)
+    except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError):
+        return None
+    if type(parsed) is type(value) and parsed == value:
+        return text
+    return None