stepfunction 0.0.3__tar.gz → 0.0.5__tar.gz

{stepfunction-0.0.3/src/StepFunction.egg-info → stepfunction-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepfunction
-Version: 0.0.3
+Version: 0.0.5
 Summary: Step Function Workflow Orchestration Library
 Author: Vineeth Penugonda
 License-Expression: MIT
@@ -22,7 +22,7 @@ Dynamic: license-file
 # StepFunction
 
 ![License](https://img.shields.io/badge/License-MIT-blue.svg)
-![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen.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.

{stepfunction-0.0.3 → stepfunction-0.0.5}/README.md

@@ -1,7 +1,7 @@
 # StepFunction
 
 ![License](https://img.shields.io/badge/License-MIT-blue.svg)
-![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen.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.

{stepfunction-0.0.3 → stepfunction-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stepfunction"
-version = "0.0.3"
+version = "0.0.5"
 authors = [{ name = "Vineeth Penugonda" }]
 description = "Step Function Workflow Orchestration Library"
 readme = "README.md"

{stepfunction-0.0.3 → stepfunction-0.0.5/src/StepFunction.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stepfunction
-Version: 0.0.3
+Version: 0.0.5
 Summary: Step Function Workflow Orchestration Library
 Author: Vineeth Penugonda
 License-Expression: MIT
@@ -22,7 +22,7 @@ Dynamic: license-file
 # StepFunction
 
 ![License](https://img.shields.io/badge/License-MIT-blue.svg)
-![Python](https://img.shields.io/badge/Python-3.12%2B-brightgreen.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.

{stepfunction-0.0.3 → stepfunction-0.0.5}/src/StepFunction.egg-info/SOURCES.txt

@@ -20,6 +20,14 @@ src/stepfunction/core/visualizer/__init__.py
 src/stepfunction/core/visualizer/visualizer.py
 src/stepfunction/exceptions/__init__.py
 src/stepfunction/exceptions/step_errors.py
+src/stepfunction/steps/__init__.py
+src/stepfunction/steps/retry_step.py
+src/stepfunction/steps/timeout_step.py
+src/stepfunction/steps/wait_step.py
+src/stepfunction/steps/base/__init__.py
+src/stepfunction/steps/base/base_step.py
+src/stepfunction/steps/exceptions/__init__.py
+src/stepfunction/steps/exceptions/step_exceptions.py
 src/stepfunction/types/__init__.py
 src/stepfunction/types/step_types.py
 src/stepfunction/types/visualizer_types.py

{stepfunction-0.0.3 → stepfunction-0.0.5}/src/stepfunction/constants/enums.py

@@ -6,3 +6,8 @@ class StepFunctionStatus(Enum):
     RUNNING = "IN_PROGRESS"
     COMPLETED = "COMPLETED"
     FAILED = "FAILED"
+
+
+class StepType(Enum):
+    INBUILT = "INBUILT"
+    EXTERNAL = "EXTERNAL"

{stepfunction-0.0.3 → stepfunction-0.0.5}/src/stepfunction/core/step_function/step_function.py

@@ -13,6 +13,7 @@ from stepfunction.exceptions.step_errors import (
     ParallelStepExecutionError,
     StepExecutionError,
 )
+from stepfunction.steps.base import BaseStep
 from stepfunction.types.step_types import StepParams
 from stepfunction.utils.logger import setup_logger
 
@@ -127,7 +128,7 @@ class StepFunction:
     def add_step(
         self,
         name: str,
-        func: Union[Callable[[Any], Any], Dict[str, Callable[[Any], Any]]],
+        func: Union[Callable[[Any], Any], Dict[str, Callable[[Any], Any]], BaseStep],
         next_step: Optional[str] = None,
         on_failure: Optional[str] = None,
         branch: Optional[Dict[Any, str]] = None,
@@ -139,6 +140,11 @@ class StepFunction:
         if name in self.__steps:
             raise ValueError(f"Step '{name}' already exists in steps")
 
+        step_type = None
+        if isinstance(func, BaseStep):
+            step_type = func.step_type
+            func = func.build()
+
         self.__steps[name] = {
             "func": func,
             "next_step": next_step,
@@ -146,6 +152,7 @@ class StepFunction:
             "branch": branch,
             "parallel": parallel,
             "stop_on_failure": stop_on_failure,
+            "step_type": step_type,
         }
 
     def add_sub_step_function(

stepfunction-0.0.5/src/stepfunction/steps/__init__.py

@@ -0,0 +1,7 @@
+from .base import BaseStep
+from .exceptions import StepTimeoutError
+from .retry_step import RetryStep
+from .timeout_step import TimeoutStep
+from .wait_step import WaitStep
+
+__all__ = ["BaseStep", "RetryStep", "StepTimeoutError", "TimeoutStep", "WaitStep"]

stepfunction-0.0.5/src/stepfunction/steps/base/__init__.py

@@ -0,0 +1,3 @@
+from .base_step import BaseStep
+
+__all__ = ["BaseStep"]

stepfunction-0.0.5/src/stepfunction/steps/base/base_step.py

@@ -0,0 +1,54 @@
+"""Base class for building custom step types.
+
+Author: Vineeth Penugonda
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from stepfunction.constants.enums import StepType
+
+
+class BaseStep(ABC):
+    """Abstract base class for building reusable, configurable step types.
+
+    Extend this class to create custom step types that encapsulate their own
+    logic and configuration. Pass an instance directly to ``StepFunction.add_step()``
+    — the framework will call ``build()`` automatically.
+
+    Class Attributes:
+        step_type (StepType): Marks the origin of the step.
+            - ``StepType.EXTERNAL`` (default) — user-defined step.
+            - ``StepType.INBUILT`` — provided by the stepfunction library.
+            Override this in your subclass only if you are building library steps.
+
+    Methods:
+        build(): Return the callable that the StepFunction will execute.
+
+    Example:
+        class MultiplyStep(BaseStep):
+            def __init__(self, factor: float):
+                self.factor = factor
+
+            def build(self) -> Callable:
+                async def run(input_value: Any) -> Any:
+                    return input_value * self.factor
+                return run
+
+        sf.add_step("double", MultiplyStep(factor=2), next_step="next")
+    """
+
+    step_type: StepType = StepType.EXTERNAL
+
+    @abstractmethod
+    def build(self) -> Callable[[Any], Any]:
+        """Return the callable that this step will execute.
+
+        The returned callable must accept a single positional argument
+        (the input value passed from the previous step) and return a value
+        that will be forwarded to the next step. It may be either a regular
+        function or a coroutine function.
+
+        Returns:
+            Callable[[Any], Any]: The step function to execute.
+        """

stepfunction-0.0.5/src/stepfunction/steps/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from .step_exceptions import StepTimeoutError
+
+__all__ = ["StepTimeoutError"]

stepfunction-0.0.5/src/stepfunction/steps/exceptions/step_exceptions.py

@@ -0,0 +1,11 @@
+"""Exceptions for built-in step types.
+
+Author: Vineeth Penugonda
+"""
+
+
+class StepTimeoutError(Exception):
+    """Raised when a step exceeds its allowed execution time."""
+
+    def __init__(self, timeout: float):
+        super().__init__(f"Step exceeded the timeout of {timeout}s")

stepfunction-0.0.5/src/stepfunction/steps/retry_step.py

@@ -0,0 +1,68 @@
+"""RetryStep — a built-in step that retries a callable on failure.
+
+Author: Vineeth Penugonda
+"""
+
+from asyncio import sleep
+from inspect import iscoroutinefunction
+from typing import Any, Callable
+
+from stepfunction.constants.enums import StepType
+from stepfunction.steps.base import BaseStep
+
+
+class RetryStep(BaseStep):
+    """A step that retries a callable on failure with a fixed delay between attempts.
+
+    Executes the wrapped function and retries up to ``max_retries`` times if it
+    raises an exception. Raises the last exception if all attempts fail.
+
+    Args:
+        func (Callable): The function to execute. May be sync or async.
+        max_retries (int): Maximum number of retry attempts after the first failure.
+            A value of 3 means the function is called at most 4 times. Defaults to 3.
+        delay (float): Seconds to wait between retry attempts. Defaults to 1.0.
+
+    Raises:
+        ValueError: If max_retries is negative or delay is negative.
+
+    Example:
+        sf.add_step("fetch", RetryStep(func=call_api, max_retries=3, delay=2.0), next_step="next")
+    """
+
+    step_type: StepType = StepType.INBUILT
+
+    def __init__(
+        self, func: Callable[[Any], Any], max_retries: int = 3, delay: float = 1.0
+    ):
+        if max_retries < 0:
+            raise ValueError("max_retries must be a non-negative integer")
+        if delay < 0:
+            raise ValueError("delay must be a non-negative number")
+
+        self.func = func
+        self.max_retries = max_retries
+        self.delay = delay
+
+    def build(self) -> Callable[[Any], Any]:
+        """Return an async function that retries ``func`` on failure."""
+        func = self.func
+        max_retries = self.max_retries
+        delay = self.delay
+
+        async def run(input_value: Any) -> Any:
+            last_exc: Exception = None
+
+            for attempt in range(max_retries + 1):
+                try:
+                    if iscoroutinefunction(func):
+                        return await func(input_value)
+                    return func(input_value)
+                except Exception as exc:
+                    last_exc = exc
+                    if attempt < max_retries:
+                        await sleep(delay)
+
+            raise last_exc
+
+        return run

stepfunction-0.0.5/src/stepfunction/steps/timeout_step.py

@@ -0,0 +1,61 @@
+"""TimeoutStep — a built-in step that enforces a maximum execution duration.
+
+Author: Vineeth Penugonda
+"""
+
+from asyncio import TimeoutError as AsyncTimeoutError
+from asyncio import get_running_loop, wait_for
+from inspect import iscoroutinefunction
+from typing import Any, Callable
+
+from stepfunction.constants.enums import StepType
+from stepfunction.steps.base import BaseStep
+from stepfunction.steps.exceptions import StepTimeoutError
+
+
+class TimeoutStep(BaseStep):
+    """A step that raises an error if the wrapped callable exceeds a time limit.
+
+    Works with both sync and async functions. Sync functions are executed in a
+    thread pool so the timeout can be enforced without blocking the event loop.
+
+    Args:
+        func (Callable): The function to execute. May be sync or async.
+        timeout (float): Maximum allowed duration in seconds.
+
+    Raises:
+        ValueError: If timeout is not a positive number.
+        StepTimeoutError: If the function does not complete within ``timeout`` seconds.
+
+    Example:
+        sf.add_step("process", TimeoutStep(func=heavy_job, timeout=30.0), next_step="next")
+    """
+
+    step_type: StepType = StepType.INBUILT
+
+    def __init__(self, func: Callable[[Any], Any], timeout: float):
+        if timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+
+        self.func = func
+        self.timeout = timeout
+
+    def build(self) -> Callable[[Any], Any]:
+        """Return an async function that enforces a timeout on ``func``."""
+        func = self.func
+        timeout = self.timeout
+
+        async def run(input_value: Any) -> Any:
+            try:
+                if iscoroutinefunction(func):
+                    return await wait_for(func(input_value), timeout=timeout)
+                else:
+                    loop = get_running_loop()
+                    return await wait_for(
+                        loop.run_in_executor(None, func, input_value),
+                        timeout=timeout,
+                    )
+            except AsyncTimeoutError:
+                raise StepTimeoutError(timeout)
+
+        return run

stepfunction-0.0.5/src/stepfunction/steps/wait_step.py

@@ -0,0 +1,41 @@
+"""WaitStep — a built-in step that pauses execution for a fixed interval.
+
+Author: Vineeth Penugonda
+"""
+
+from asyncio import sleep
+from typing import Any, Callable
+
+from stepfunction.constants.enums import StepType
+from stepfunction.steps.base import BaseStep
+
+
+class WaitStep(BaseStep):
+    """A step that pauses workflow execution for a fixed duration.
+
+    The input value is passed through unchanged so the next step receives
+    exactly what the previous step produced.
+
+    Args:
+        duration (float): Number of seconds to wait before proceeding.
+
+    Example:
+        sf.add_step("pause", WaitStep(duration=5), next_step="next_step")
+    """
+
+    step_type: StepType = StepType.INBUILT
+
+    def __init__(self, duration: float):
+        if duration < 0:
+            raise ValueError("duration must be a non-negative number")
+        self.duration = duration
+
+    def build(self) -> Callable[[Any], Any]:
+        """Return an async function that sleeps for ``duration`` seconds."""
+        duration = self.duration
+
+        async def wait(input_value: Any) -> Any:
+            await sleep(duration)
+            return input_value
+
+        return wait

{stepfunction-0.0.3 → stepfunction-0.0.5}/src/stepfunction/types/step_types.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable, Dict, Optional, TypedDict, Union
 
+from stepfunction.constants.enums import StepType
+
 
 class StepParams(TypedDict, total=False):
     func: Callable[[Any], Any]
@@ -9,3 +11,4 @@ class StepParams(TypedDict, total=False):
     parallel: bool
     stop_on_failure: bool
     is_sub_step_function: bool
+    step_type: Optional[StepType]