stepfunction 0.0.6__tar.gz → 0.2.0__tar.gz

{stepfunction-0.0.6/src/StepFunction.egg-info → stepfunction-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepfunction
-Version: 0.0.6
+Version: 0.2.0
 Summary: Step Function Workflow Orchestration Library
 Author: Vineeth Penugonda
 License-Expression: MIT
@@ -16,7 +16,6 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: graphviz===0.20.3
 Dynamic: license-file
 
 # StepFunction
@@ -33,7 +32,40 @@ Dynamic: license-file
 - **Error Handling**: Define failure paths and handle exceptions gracefully.
 - **Branching Logic**: Direct workflows based on conditions.
 - **Sub-Step Functions**: Modularize workflows by embedding sub-step functions.
-- **Visualization**: Integrated support for visualizing the workflow graph.
+- **Visualization**: Integrated support for visualizing the workflow graph as a Mermaid flowchart.
+- **Lifecycle Hooks**: Get notified as the workflow and each step start, succeed or fail — with inputs, outputs, errors, routing and timings — to record run history, metrics or traces.
+
+## Lifecycle Hooks
+
+Subclass `StepFunctionHooks`, override the events you need (sync or async), and pass an instance to the step function:
+
+```python
+from stepfunction.core.step_function import StepFunction
+from stepfunction.hooks import StepEvent, StepFunctionHooks
+
+
+class RunRecorder(StepFunctionHooks):
+    async def on_step_start(self, event: StepEvent):
+        print(f"{event.workflow}: {event.step} started with {event.input!r}")
+
+    async def on_step_success(self, event: StepEvent):
+        print(f"{event.step} -> {event.output!r} in {event.duration:.3f}s, next: {event.next_step}")
+
+    async def on_step_failure(self, event: StepEvent):
+        print(f"{event.step} failed: {event.error!r}, next: {event.next_step}")
+
+
+sf = StepFunction("MyStepFunction", hooks=RunRecorder())
+```
+
+Events: `on_workflow_start`, `on_step_start`, `on_step_success`, `on_step_failure`, `on_workflow_end`.
+
+- `StepEvent` carries the workflow path, step name, parallel `task` name (if any), `input`, `output`, the original `error`, the resolved `next_step`, UTC `started_at` / `finished_at` and `duration` in seconds.
+- `WorkflowEvent` carries the workflow path, `status`, initial `input`, final `output`, the `error` that ended the run (if `execute()` raised) and timings.
+- Each task of a parallel step is reported as its own step event, with `task` set.
+- A sub-step function without hooks of its own reports to its parent's hooks; its events carry the nested path, e.g. `"FLOW -> SubStep (SUB_FLOW)"`.
+- Hooks observe; they don't steer. An exception raised by a hook is logged and ignored.
+- If the run is cancelled, the running step and the workflow are reported with the `CancelledError`, which is then re-raised.
 
 ## Installation
 
@@ -49,11 +81,7 @@ For more detailed usage examples and advanced use cases, please read the [blog p
 
 ## Dependencies
 
-The StepFunction package requires the following dependencies:
-
-- `graphviz == 0.20.3`
-
-These will be automatically installed when you install the package via pip.
+The StepFunction package has no required runtime dependencies. Workflow visualization renders directly to [Mermaid](https://mermaid.js.org/) flowchart syntax (`.mmd`), which can be previewed in VS Code, GitHub/Bitbucket markdown, or https://mermaid.live without any additional tooling.
 
 ## Contributing
 

stepfunction-0.2.0/README.md

@@ -0,0 +1,75 @@
+# StepFunction
+
+![License](https://img.shields.io/badge/License-MIT-blue.svg)
+![Python](https://img.shields.io/badge/Python-3.9%2B-brightgreen.svg)
+![Status](https://img.shields.io/badge/Status-Alpha-red.svg)
+
+`StepFunction` is a Python library for orchestrating complex workflows through a step-by-step process. It allows for easy management of sequential and parallel tasks with robust error handling and branching. The library is inspired by AWS Step Functions but implemented as a Python-native solution to orchestrate workflows across any environment.
+
+## Features
+
+- **Sequential and Parallel Execution**: Run steps one after another or in parallel.
+- **Error Handling**: Define failure paths and handle exceptions gracefully.
+- **Branching Logic**: Direct workflows based on conditions.
+- **Sub-Step Functions**: Modularize workflows by embedding sub-step functions.
+- **Visualization**: Integrated support for visualizing the workflow graph as a Mermaid flowchart.
+- **Lifecycle Hooks**: Get notified as the workflow and each step start, succeed or fail — with inputs, outputs, errors, routing and timings — to record run history, metrics or traces.
+
+## Lifecycle Hooks
+
+Subclass `StepFunctionHooks`, override the events you need (sync or async), and pass an instance to the step function:
+
+```python
+from stepfunction.core.step_function import StepFunction
+from stepfunction.hooks import StepEvent, StepFunctionHooks
+
+
+class RunRecorder(StepFunctionHooks):
+    async def on_step_start(self, event: StepEvent):
+        print(f"{event.workflow}: {event.step} started with {event.input!r}")
+
+    async def on_step_success(self, event: StepEvent):
+        print(f"{event.step} -> {event.output!r} in {event.duration:.3f}s, next: {event.next_step}")
+
+    async def on_step_failure(self, event: StepEvent):
+        print(f"{event.step} failed: {event.error!r}, next: {event.next_step}")
+
+
+sf = StepFunction("MyStepFunction", hooks=RunRecorder())
+```
+
+Events: `on_workflow_start`, `on_step_start`, `on_step_success`, `on_step_failure`, `on_workflow_end`.
+
+- `StepEvent` carries the workflow path, step name, parallel `task` name (if any), `input`, `output`, the original `error`, the resolved `next_step`, UTC `started_at` / `finished_at` and `duration` in seconds.
+- `WorkflowEvent` carries the workflow path, `status`, initial `input`, final `output`, the `error` that ended the run (if `execute()` raised) and timings.
+- Each task of a parallel step is reported as its own step event, with `task` set.
+- A sub-step function without hooks of its own reports to its parent's hooks; its events carry the nested path, e.g. `"FLOW -> SubStep (SUB_FLOW)"`.
+- Hooks observe; they don't steer. An exception raised by a hook is logged and ignored.
+- If the run is cancelled, the running step and the workflow are reported with the `CancelledError`, which is then re-raised.
+
+## Installation
+
+You can install the `StepFunction` package using `pip`:
+
+```bash
+pip install stepfunction
+```
+
+## Documentation and Further Reading
+
+For more detailed usage examples and advanced use cases, please read the [blog post](https://blog.vineethp.com/posts/introducingstepfunction/) that explains the design and usage of the library in-depth. This blog post covers advanced concepts like error handling, sub-step functions, and visualizing workflows in a real-world context.
+
+## Dependencies
+
+The StepFunction package has no required runtime dependencies. Workflow visualization renders directly to [Mermaid](https://mermaid.js.org/) flowchart syntax (`.mmd`), which can be previewed in VS Code, GitHub/Bitbucket markdown, or https://mermaid.live without any additional tooling.
+
+## Contributing
+
+If you'd like to contribute to StepFunction, feel free to submit issues or pull requests. Contributions are welcome!
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Author
+Created and maintained by **Vineeth Penugonda**.

{stepfunction-0.0.6 → stepfunction-0.2.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "stepfunction"
-version = "0.0.6"
+version = "0.2.0"
 authors = [{ name = "Vineeth Penugonda" }]
 description = "Step Function Workflow Orchestration Library"
 readme = "README.md"
 keywords = ["StepFunction", "Workflow", "Orchestration", "Library"]
 requires-python = ">=3.9"
-dependencies = ["graphviz === 0.20.3"]
+dependencies = []
 license = "MIT"
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -26,7 +26,7 @@ ignore = ["E501"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
-include = ["stepfunction.*"]
+include = ["stepfunction", "stepfunction.*"]
 
 [project.urls]
 Homepage = "https://github.com/vinecodes/stepfunction"

stepfunction-0.2.0/src/stepfunction/constants/visualizer.py

@@ -0,0 +1,53 @@
+# Visualizer
+
+# Render Configuration
+
+DEFAULT_VISUALIZER_DIRECTION = "TD"
+"""str: The default flowchart direction for the Mermaid visualizer (e.g. TD, LR)."""
+
+DEFAULT_VISUALIZER_EXTENSION = "mmd"
+"""str: The default file extension for the visualizer renderer output."""
+
+DEFAULT_VISUALIZER_FOLDER = "workflow_renders"
+"""str: The default folder where visualizer renders are stored."""
+
+DEFAULT_VISUALIZER_STRING_ENCODING = "utf-8"
+"""str: The default encoding for visualizer strings."""
+
+# Edge labels and colors
+
+DEFAULT_VISUALIZER_SUCCESS_EDGE_LABEL = "Success"
+"""str: The default edge label for success transitions in the visualizer."""
+
+DEFAULT_VISUALIZER_FAILURE_EDGE_LABEL = "Failure"
+"""str: The default edge label for failure transitions in the visualizer."""
+
+DEFAULT_VISUALIZER_STOP_ON_FAILURE_EDGE_LABEL = "Stop on Failure"
+"""str: The default edge label for stop on failure transitions in the visualizer."""
+
+DEFAULT_VISUALIZER_STOP_ON_FAILURE_EDGE_COLOR = "red"
+"""str: The default edge color for stop on failure transitions in the visualizer."""
+
+DEFAULT_VISUALIZER_BRANCH_EDGE_LABEL_PREFIX = "Branch"
+"""str: The default edge label prefix for branch transitions in the visualizer."""
+
+DEFAULT_VISUALIZER_BRANCH_DEFAULT_LABEL = "else"
+"""str: The label used for an unconditional (fallback) branch return."""
+
+DEFAULT_VISUALIZER_MAX_BRANCH_LABEL_LENGTH = 60
+"""int: The maximum length of a branch condition label before it's truncated."""
+
+# Node styling (Mermaid classDef names)
+
+DEFAULT_VISUALIZER_SUB_STEP_FUNCTION_CLASS = "subStepFunction"
+"""str: The Mermaid classDef name applied to sub-step function nodes."""
+
+DEFAULT_VISUALIZER_SUB_STEP_FUNCTION_CLASS_STYLE = (
+    "fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5"
+)
+"""str: The Mermaid classDef style applied to sub-step function nodes."""
+
+# Node ID sanitization
+
+VISUALIZER_INVALID_NODE_ID_CHARS = r"[^0-9A-Za-z_]"
+"""str: Regex matching characters not allowed in a Mermaid node ID; matches are replaced with "_"."""

stepfunction-0.2.0/src/stepfunction/core/serializer/__init__.py

@@ -0,0 +1,3 @@
+from .serializer import decode_step_function, encode_step_function
+
+__all__ = ["decode_step_function", "encode_step_function"]

stepfunction-0.2.0/src/stepfunction/core/serializer/serializer.py

@@ -0,0 +1,170 @@
+"""Encode/decode logic for declarative (JSON-able dict) StepFunction specs.
+
+Author: Vineeth Penugonda
+"""
+
+from typing import Any, Callable, Dict, Optional, cast
+
+from stepfunction.core.step_function.step_function import StepFunction
+from stepfunction.exceptions.step_errors import (
+    UnregisteredFunctionError,
+    UnserializableStepError,
+)
+from stepfunction.registry.step_registry import StepRegistry
+from stepfunction.registry.step_registry import registry as default_registry
+from stepfunction.types.step_types import StepParams
+
+
+def _name_for_or_raise(
+    step_registry: StepRegistry, func: Callable[[Any], Any], step_name: str
+) -> str:
+    name = step_registry.name_for(func)
+    if name is None:
+        raise UnregisteredFunctionError(
+            f"The function used in step '{step_name}' is not registered in the "
+            "given registry, so its name can't be determined for export. "
+            "Register it with stepfunction.registry.step_registry.register_step() first."
+        )
+    return name
+
+
+def _encode_step(
+    step_name: str, step: StepParams, step_registry: StepRegistry
+) -> Dict[str, Any]:
+    if step["step_type"] is not None:
+        raise UnserializableStepError(step_name, step["step_type"])
+
+    encoded: Dict[str, Any] = {
+        "next_step": step["next_step"],
+        "on_failure": step["on_failure"],
+        "parallel": step["parallel"],
+        "stop_on_failure": step["stop_on_failure"],
+    }
+
+    if step["is_sub_step_function"]:
+        sub_step_function = cast(StepFunction, step["sub_step_function"])
+        encoded["sub_step_function"] = encode_step_function(
+            sub_step_function, step_registry
+        )
+        return encoded
+
+    if step["parallel"]:
+        func_map = cast(Dict[str, Callable[[Any], Any]], step["func"])
+        encoded["func"] = {
+            slot: _name_for_or_raise(step_registry, fn, step_name)
+            for slot, fn in func_map.items()
+        }
+    else:
+        func = cast(Callable[[Any], Any], step["func"])
+        encoded["func"] = _name_for_or_raise(step_registry, func, step_name)
+
+    branch = step["branch"]
+    if branch is not None:
+        if callable(branch):
+            encoded["branch"] = _name_for_or_raise(step_registry, branch, step_name)
+        else:
+            encoded["branch"] = {str(key): value for key, value in branch.items()}
+
+    return encoded
+
+
+def encode_step_function(
+    sf: StepFunction, step_registry: Optional[StepRegistry] = None
+) -> Dict[str, Any]:
+    """Export ``sf`` as a JSON-able dict.
+
+    Recurses into nested sub-step-functions by calling itself again, so
+    arbitrary nesting depth is handled without special-casing.
+
+    Raises:
+        UnserializableStepError: If any step was built from a BaseStep
+            instance (RetryStep, TimeoutStep, WaitStep, or a custom
+            BaseStep subclass) — not yet supported.
+        UnregisteredFunctionError: If a step or branch function used in
+            ``sf`` has no registered name in ``step_registry``.
+    """
+    step_registry = step_registry or default_registry
+
+    return {
+        "name": sf.name,
+        "start_step": sf.current_step,
+        "steps": {
+            step_name: _encode_step(step_name, step, step_registry)
+            for step_name, step in sf.steps.items()
+        },
+    }
+
+
+def decode_step_function(
+    data: Dict[str, Any],
+    step_registry: Optional[StepRegistry] = None,
+    _validate: bool = True,
+) -> StepFunction:
+    """Reconstruct a StepFunction from a dict produced by ``encode_step_function``.
+
+    Rebuilds the workflow purely through ``add_step``/``add_sub_step_function``/
+    ``set_start_step`` — the same public API a user would call by hand — and
+    recurses into nested "sub_step_function" entries by calling itself again.
+    Validates exactly once, at the very end, at the outermost level only:
+    ``StepFunction.validate()`` already recurses into sub-step functions and
+    reports a readable breadcrumb across nesting levels, so a malformed
+    nested spec still fails fast without the decoder needing its own
+    recursive validation pass.
+
+    Raises:
+        UnregisteredFunctionError: If a referenced function name isn't
+            registered in ``step_registry`` (defaults to the package's
+            default singleton registry if not given).
+        ValueError: If the reconstructed workflow fails validate().
+    """
+    step_registry = step_registry or default_registry
+
+    sf = StepFunction(data["name"])
+
+    for step_name, step_data in data["steps"].items():
+        if "sub_step_function" in step_data:
+            sub_step_function = decode_step_function(
+                step_data["sub_step_function"], step_registry, _validate=False
+            )
+            sf.add_sub_step_function(
+                step_name,
+                sub_step_function=sub_step_function,
+                next_step=step_data.get("next_step"),
+                on_failure=step_data.get("on_failure"),
+            )
+            continue
+
+        func_spec = step_data["func"]
+        if isinstance(func_spec, dict):
+            func: Any = {
+                slot: step_registry.get(ref) for slot, ref in func_spec.items()
+            }
+        else:
+            func = step_registry.get(func_spec)
+
+        branch_spec = step_data.get("branch")
+        if branch_spec is None:
+            branch: Any = None
+        elif isinstance(branch_spec, dict):
+            branch = dict(branch_spec)
+        else:
+            branch = step_registry.get(branch_spec)
+
+        sf.add_step(
+            step_name,
+            func,
+            next_step=step_data.get("next_step"),
+            on_failure=step_data.get("on_failure"),
+            branch=branch,
+            parallel=step_data.get("parallel", False),
+            stop_on_failure=step_data.get("stop_on_failure", False),
+        )
+
+    start_step = data.get("start_step")
+    if start_step is not None:
+        sf.set_start_step(start_step)
+
+    if _validate:
+        sf.validate()
+
+    return sf