flowrep 0.4.1__tar.gz → 0.5.1__tar.gz

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

@@ -1,5 +1,6 @@
 *.pyc
 .DS_Store
+.claude/
 .coverage
 .pre-commit-config.yaml
 nohup.out
@@ -10,5 +11,6 @@ _build/
 apidoc/
 .ipynb_checkpoints/
 test_times.dat
+CLAUDE.md
 core.*
 src/flowrep/_version.py

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowrep
-Version: 0.4.1
+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.3; extra == 'notebooks'
+Requires-Dist: numpy==2.4.6; extra == 'notebooks'
 Provides-Extra: pwd
-Requires-Dist: python-workflow-definition==0.1.4; extra == 'pwd'
+Requires-Dist: python-workflow-definition==0.1.5; extra == 'pwd'
 Provides-Extra: storage
-Requires-Dist: bagofholding==0.1.10; extra == 'storage'
+Requires-Dist: bagofholding==0.1.12; extra == 'storage'
 Provides-Extra: storage-widget
-Requires-Dist: bagofholding==0.1.10; 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
 
@@ -76,10 +76,11 @@ Description-Content-Type: text/markdown
 ## flowrep — Workflow Recipes from Python
 
 **flowrep** turns plain Python functions into shareable, versionable *workflow
-recipes* — JSON-serialisable graphs that describe *what* to compute (which
+recipes* — JSON-serialisable "class view" graphs that describe *what* to compute (which
 functions, how they connect) without doing the computation or holding any data.
 Recipes are prospective blueprints that a Workflow Management System (WfMS) can
-digest, visualise, and execute.
+digest, visualise, and execute. To support this, **flowrep** also provides a set of 
+retrospective, "instance view" data classes for WfMS to populate when executing recipes.
 
 Flowchart-style representations are already the lingua franca for describing
 processes in science and engineering. flowrep gives you a way to author them in
@@ -209,6 +210,11 @@ control structures you use in real code. Flow control nodes are inherently
 dynamic: their exact execution path depends on data and cannot be known until
 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.
@@ -307,34 +313,30 @@ the decorated functions are still just python functions; second, to show in the
 section that the recipe we parse from this are intended to give the same result as 
 these underlying functions when we run the recipe with a WfMS.
 
-## Beyond Recipes: Live Data and Execution
+## Beyond Recipes: Retrospective "Instance View" Data and Execution
 
 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.recipe2live`** converts a recipe into a *live* object — a mutable
-data structure whose input and output ports can hold actual Python values. Live
-objects mirror the recipe graph but trade JSON-serializability for the ability to
-carry arbitrary data:
+**`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
->>> live_wf = frt.recipe2live(double_and_add.flowrep_recipe)
+>>> wf_data = fr.tools.recipe2data(double_and_add.flowrep_recipe)
 
 ```
 
 **`flowrep.api.tools.run_recipe`** goes one step further: it executes the recipe with
-the provided inputs and returns a fully populated live object. This is powered
+the provided inputs and returns a fully populated data object. This is powered
 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
@@ -342,8 +344,8 @@ in tests and documentation (like this!):
 
 ```
 
-Because every child node's ports are populated too, the live graph gives you
-full data provenance — you can walk the tree and inspect exactly what each node
+Because every child node's ports are populated too, the retrospective data graph gives 
+you full data provenance — you can walk the tree and inspect exactly what each node
 received and produced.
 For flow control nodes, which are _prospectively_ "black boxes", we find that 
 _retrospectively_ they are simple DAGs.
@@ -360,14 +362,13 @@ each loop iteration:
 ```
 
 For a deeper look at all available node types, edge semantics, version
-provenance, and the live/WfMS layer, see the
+provenance, and the retropective data/WfMS layer, see the
 [user guide](https://mybinder.org/v2/gh/pyiron/flowrep/HEAD?urlpath=%2Fdoc%2Ftree%2Fuser-guide.ipynb).
 
 
 ## Documentation
 
-- The user guide notebook comprehensively covers all node types, edge models, flow control, versioning, 
-  live/retrospective data formats, a demo WfMS implementation, and recipe format converters. 
+- The user guide notebook comprehensively covers all node types, edge models, flow control, versioning, retrospective data formats, a demo WfMS implementation, and recipe format converters. 
   Launch it interactively on
   [mybinder](https://mybinder.org/v2/gh/pyiron/flowrep/HEAD?urlpath=%2Fdoc%2Ftree%2Fuser-guide.ipynb).
 - [readthedocs](https://flowrep.readthedocs.io/en/latest/)

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

@@ -14,10 +14,11 @@
 ## flowrep — Workflow Recipes from Python
 
 **flowrep** turns plain Python functions into shareable, versionable *workflow
-recipes* — JSON-serialisable graphs that describe *what* to compute (which
+recipes* — JSON-serialisable "class view" graphs that describe *what* to compute (which
 functions, how they connect) without doing the computation or holding any data.
 Recipes are prospective blueprints that a Workflow Management System (WfMS) can
-digest, visualise, and execute.
+digest, visualise, and execute. To support this, **flowrep** also provides a set of 
+retrospective, "instance view" data classes for WfMS to populate when executing recipes.
 
 Flowchart-style representations are already the lingua franca for describing
 processes in science and engineering. flowrep gives you a way to author them in
@@ -147,6 +148,11 @@ control structures you use in real code. Flow control nodes are inherently
 dynamic: their exact execution path depends on data and cannot be known until
 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.
@@ -245,34 +251,30 @@ the decorated functions are still just python functions; second, to show in the
 section that the recipe we parse from this are intended to give the same result as 
 these underlying functions when we run the recipe with a WfMS.
 
-## Beyond Recipes: Live Data and Execution
+## Beyond Recipes: Retrospective "Instance View" Data and Execution
 
 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.recipe2live`** converts a recipe into a *live* object — a mutable
-data structure whose input and output ports can hold actual Python values. Live
-objects mirror the recipe graph but trade JSON-serializability for the ability to
-carry arbitrary data:
+**`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
->>> live_wf = frt.recipe2live(double_and_add.flowrep_recipe)
+>>> wf_data = fr.tools.recipe2data(double_and_add.flowrep_recipe)
 
 ```
 
 **`flowrep.api.tools.run_recipe`** goes one step further: it executes the recipe with
-the provided inputs and returns a fully populated live object. This is powered
+the provided inputs and returns a fully populated data object. This is powered
 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
@@ -280,8 +282,8 @@ in tests and documentation (like this!):
 
 ```
 
-Because every child node's ports are populated too, the live graph gives you
-full data provenance — you can walk the tree and inspect exactly what each node
+Because every child node's ports are populated too, the retrospective data graph gives 
+you full data provenance — you can walk the tree and inspect exactly what each node
 received and produced.
 For flow control nodes, which are _prospectively_ "black boxes", we find that 
 _retrospectively_ they are simple DAGs.
@@ -298,14 +300,13 @@ each loop iteration:
 ```
 
 For a deeper look at all available node types, edge semantics, version
-provenance, and the live/WfMS layer, see the
+provenance, and the retropective data/WfMS layer, see the
 [user guide](https://mybinder.org/v2/gh/pyiron/flowrep/HEAD?urlpath=%2Fdoc%2Ftree%2Fuser-guide.ipynb).
 
 
 ## Documentation
 
-- The user guide notebook comprehensively covers all node types, edge models, flow control, versioning, 
-  live/retrospective data formats, a demo WfMS implementation, and recipe format converters. 
+- The user guide notebook comprehensively covers all node types, edge models, flow control, versioning, retrospective data formats, a demo WfMS implementation, and recipe format converters. 
   Launch it interactively on
   [mybinder](https://mybinder.org/v2/gh/pyiron/flowrep/HEAD?urlpath=%2Fdoc%2Ftree%2Fuser-guide.ipynb).
 - [readthedocs](https://flowrep.readthedocs.io/en/latest/)

{flowrep-0.4.1 → 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"
@@ -28,9 +28,9 @@ Documentation = "https://flowrep.readthedocs.io"
 Repository = "https://github.com/pyiron/flowrep"
 
 [project.optional-dependencies]
-pwd = [ "python-workflow-definition==0.1.4",]
-notebooks = [ "numpy==2.4.3",]
-storage = [ "bagofholding==0.1.10",]
+pwd = [ "python-workflow-definition==0.1.5",]
+notebooks = [ "numpy==2.4.6",]
+storage = [ "bagofholding==0.1.12",]
 storage-widget = [ "flowrep[storage]", "ipytree==0.2.2",]
 
 [tool.ruff]

{flowrep-0.4.1 → 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.1/src/flowrep/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__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.4.1 → flowrep-0.5.1}/src/flowrep/base_models.py

@@ -69,7 +69,7 @@ UniqueList = Annotated[list[T], pydantic.AfterValidator(validate_unique)]
 Labels = UniqueList[Label]
 
 
-class NodeModel(pydantic.BaseModel):
+class NodeRecipe(pydantic.BaseModel):
     type: RecipeElementType
     inputs: Labels
     outputs: Labels
@@ -78,7 +78,7 @@ class NodeModel(pydantic.BaseModel):
     @classmethod
     def __pydantic_init_subclass__(cls, **kwargs):
         super().__pydantic_init_subclass__(**kwargs)
-        if cls.__name__ != NodeModel.__name__:  # I.e. for subclasses
+        if cls.__name__ != NodeRecipe.__name__:  # I.e. for subclasses
             type_field = cls.model_fields["type"]
             if type_field.default is pydantic_core.PydanticUndefined:
                 raise TypeError(

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