iterativerecursion 1.0__py3-none-any.whl

iterativerecursion/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+
+from iterativerecursion.iterativerecursion import IterativeRecursionEngine
+from iterativerecursion.iterativerecursion import FunctionReturn
+from iterativerecursion.iterativerecursion import VarsDict

iterativerecursion/iterativerecursion.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+VarsDict = dict[str, Any]
+
+
+@dataclass
+class FunctionReturn:
+    """
+    Return type for functions executed by IterativeRecursionEngine.
+
+    Attributes:
+        returned_values: Dictionary of values to update in the environment.
+        next_function_to_call: Name of the next function to execute, or None to
+            terminate execution.
+        arg_env_mapping: Mapping of parameter names to environment variable keys
+            for the next function call. If not provided, automatically maps
+            returned_values keys to themselves (e.g., {"x": 5} maps to {"x": "x"}).
+
+    Example:
+        # Simplest form - auto-mapping
+        return FunctionReturn(
+            returned_values={"counter": counter + 1},
+            next_function_to_call="infinite_loop"
+        )
+
+        # Custom mapping when needed
+        return FunctionReturn(
+            returned_values={"result": 42},
+            next_function_to_call="process",
+            arg_env_mapping={"input": "result"}  # Maps param 'input' to env var 'result'
+        )
+    """
+    returned_values: dict[str, Any]
+    next_function_to_call: str | None = None
+    arg_env_mapping: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Auto-populate arg_env_mapping if not provided."""
+        if not self.arg_env_mapping:
+            # Map each returned value key to itself
+            self.arg_env_mapping = {k: k for k in self.returned_values.keys()}
+
+
+class IterativeRecursionEngine:
+    """
+    Execute functions and "call" between them without recursion.
+
+    You have a dict of variables on self.environment_variables that work as
+    "global variables" inside of the executor.
+
+    When you call a function, the values that return will update
+    self.environment_variables, you pass only self.environment_variables
+    as arguments to a function.
+    """
+    def __init__(self):
+        self.functions_dict: dict[str, Callable[..., FunctionReturn]] = {}
+        self.environment_variables: VarsDict = {}
+
+    def _validate_function_return(self, resp: Any, func_name: str) -> None:
+        """
+        Validate function return is a FunctionReturn instance.
+
+        :param resp: The return value from a function
+        :param func_name: Name of the function that returned the value
+        :raises TypeError: If return value is not a FunctionReturn instance
+        """
+        if not isinstance(resp, FunctionReturn):
+            raise TypeError(
+                f"Function '{func_name}' must return a FunctionReturn instance, "
+                f"got {type(resp).__name__}. "
+                f"Example: return FunctionReturn(returned_values={{'x': 5}}, next_function_to_call='next_func')"
+            )
+
+        # Validate types (dataclass doesn't enforce at runtime)
+        if not isinstance(resp.arg_env_mapping, dict):
+            raise TypeError(
+                f"Function '{func_name}': arg_env_mapping must be dict, "
+                f"got {type(resp.arg_env_mapping).__name__}"
+            )
+
+        if resp.next_function_to_call is not None and not isinstance(
+            resp.next_function_to_call, str
+        ):
+            raise TypeError(
+                f"Function '{func_name}': next_function_to_call must be str or None, "
+                f"got {type(resp.next_function_to_call).__name__}"
+            )
+
+        if not isinstance(resp.returned_values, dict):
+            raise TypeError(
+                f"Function '{func_name}': returned_values must be dict, "
+                f"got {type(resp.returned_values).__name__}"
+            )
+
+    def _resolve_arguments(
+        self, arg_env_mapping: dict[str, str], func_name: str
+    ) -> dict[str, Any]:
+        """
+        Resolve argument names to actual values from environment.
+
+        :param arg_env_mapping: Mapping of parameter names to environment variable keys
+        :param func_name: Name of the function (for error messages)
+        :return: Dictionary mapping parameter names to actual values
+        :raises KeyError: If required environment variables are missing
+        """
+        missing_vars = set(arg_env_mapping.values()) - self.environment_variables.keys()
+        if missing_vars:
+            available = set(self.environment_variables.keys())
+            raise KeyError(
+                f"Function '{func_name}' requires environment variables "
+                f"that don't exist: {missing_vars}. "
+                f"Available variables: {available if available else '(none)'}"
+            )
+
+        return {
+            arg: self.environment_variables[env_key]
+            for arg, env_key in arg_env_mapping.items()
+        }
+
+    def start_function_caller(
+        self,
+        next_function_to_call: str,
+        environment_variables: VarsDict,
+        arg_env_mapping: VarsDict,
+        max_iterations: int | None = None
+    ) -> VarsDict:
+        """
+        Start the execution of a function.
+
+        :param next_function_to_call: What function to call first when starting
+            this function. If next_function_to_call is None, this function stops
+            and returns.
+        :param environment_variables: Variables to add to the environment.
+        :param arg_env_mapping: Arguments to call on the first function.
+        :param max_iterations: Maximum number of function calls allowed before
+            raising an error. None means unlimited iterations. Defaults to None.
+        :return: The final state of environment_variables after execution completes
+        :raises RuntimeError: If max_iterations limit is reached
+        :raises KeyError: If function not found or environment variable missing
+        :raises ValueError: If function returns invalid structure
+        :raises TypeError: If function return has wrong types
+        """
+        if next_function_to_call is None:
+            return self.environment_variables
+
+        self.environment_variables.update(environment_variables)
+
+        # Resolve initial arguments
+        arg_env_mapping = self._resolve_arguments(arg_env_mapping, next_function_to_call)
+
+        iteration_count = 0
+        while True:
+            # Check iteration limit
+            if max_iterations is not None:
+                if iteration_count >= max_iterations:
+                    raise RuntimeError(
+                        f"Maximum iteration limit ({max_iterations}) reached. "
+                        f"This may indicate an infinite loop. "
+                        f"Last function called: {next_function_to_call}"
+                    )
+                iteration_count += 1
+
+            # Execute function
+            resp = self.functions_dict[next_function_to_call](**arg_env_mapping)
+
+            # Validate return structure
+            self._validate_function_return(resp, next_function_to_call)
+
+            # Update environment with returned values
+            self.environment_variables.update(resp.returned_values)
+
+            # Determine next function to call
+            next_function_to_call = resp.next_function_to_call
+            if not next_function_to_call:
+                return self.environment_variables
+            elif next_function_to_call not in self.functions_dict:
+                available_funcs = set(self.functions_dict.keys())
+                raise KeyError(
+                    f"Function '{next_function_to_call}' not found in registry. "
+                    f"Available functions: {available_funcs if available_funcs else '(none)'}"
+                )
+
+            # Resolve arguments for next function call
+            arg_env_mapping = self._resolve_arguments(
+                resp.arg_env_mapping, next_function_to_call
+            )
+
+    def add_environment_variables(self, environment_variables_dict_update: VarsDict):
+        """
+        Define new variables inside of the executor.
+
+        :param environment_variables_dict_update: Dict of new variables to add.
+        """
+        self.environment_variables.update(environment_variables_dict_update)
+
+    def add_function(self, function: Callable[..., FunctionReturn]) -> None:
+        """
+        Define new functions inside of the executor.
+
+        :param function: Function to add. Must return FunctionReturn structure.
+        """
+        self.functions_dict[function.__name__] = function
+
+    def register(self, func: Callable[..., FunctionReturn]) -> Callable[..., FunctionReturn]:
+        """
+        Decorator to register a function with the engine.
+
+        Example:
+            @engine.register
+            def my_func(x: int) -> FunctionReturn:
+                return FunctionReturn(
+                    returned_values={"result": x * 2},
+                    next_function_to_call=None
+                )
+
+        :param func: Function to register
+        :return: The same function (for chaining)
+        """
+        self.add_function(func)
+        return func

iterativerecursion-1.0.dist-info/METADATA

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: iterativerecursion
+Version: 1.0
+Summary: A Python module to simulate recursive function calls using iteration, providing explicit control over execution flow and avoiding stack overflow issues.
+Author-email: "Carlos A. Planchón" <carlosandresplanchonprestes@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/carlosplanchon/iterativerecursion
+Keywords: iterative,recursion
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# iterativerecursion
+
+![iterativerecursion banner](https://raw.githubusercontent.com/carlosplanchon/iterativerecursion/refs/heads/master/assets/banner.jpeg)
+
+*A Python module to simulate recursive function calls using iteration, providing explicit control over execution flow and avoiding stack overflow issues.*
+
+## Overview
+
+`iterativerecursion` provides a mechanism to chain function calls iteratively while maintaining a recursive-like pattern. Instead of relying on the call stack, functions explicitly declare what to call next, making the execution flow transparent and controllable.
+
+### Why Use This?
+
+- **Avoid Stack Overflow**: Handle deep recursion without hitting Python's recursion limit
+- **Explicit Control**: See and control the exact flow of function calls
+- **Debugging**: Easier to trace execution without deep call stacks
+- **State Management**: Shared environment for passing data between functions
+- **Safety**: Built-in iteration limits to prevent infinite loops
+
+### When to Use This
+
+This library is useful when you need:
+- Deep recursion that exceeds Python's stack limit (~1000 calls)
+- Explicit control over recursive execution flow
+- To convert recursive algorithms to iterative ones systematically
+- State machines or complex control flow patterns
+
+## Scope & limitations
+
+This engine is essentially a **trampoline / dispatcher**: each step returns the name of the next function to run.
+That makes it a great fit for **tail recursion (linear step-by-step recursion)**, workflows, and state machines.
+
+It does **not** automatically emulate a full call stack. Patterns that require “returning to the caller”
+(e.g. tree recursion like `fib(n-1) + fib(n-2)`, post-order DFS reductions) require you to model an explicit
+stack/frames (continuations) inside `environment_variables`.
+
+For most cases, **normal recursion is simpler and preferred**. Use this when recursion depth or explicit control becomes a concern.
+
+## Documentation
+
+📚 **[View interactive documentation on DeepWiki](https://deepwiki.com/carlosplanchon/iterativerecursion)**
+
+Explore the full API reference, examples, and guides in an interactive format.
+
+## Installation
+
+### Using uv
+```bash
+uv add iterativerecursion
+```
+
+### Using pip
+```bash
+pip install iterativerecursion
+```
+
+## Quick Start
+
+```python
+from iterativerecursion import IterativeRecursionEngine, FunctionReturn
+
+def greet(name: str) -> FunctionReturn:
+    print(f"Hello, {name}!")
+    return FunctionReturn(
+        returned_values={"next_name": "World"},
+        next_function_to_call="farewell",
+        arg_env_mapping={"name": "next_name"}
+    )
+
+def farewell(name: str) -> FunctionReturn:
+    print(f"Goodbye, {name}!")
+    return FunctionReturn(
+        returned_values={}
+        # next_function_to_call defaults to None to terminate
+    )
+
+# Create engine and register functions
+engine = IterativeRecursionEngine()
+engine.add_function(greet)
+engine.add_function(farewell)
+
+# Start execution
+engine.start_function_caller(
+    next_function_to_call="greet",
+    environment_variables={"initial_name": "Alice"},
+    arg_env_mapping={"name": "initial_name"}
+)
+```
+
+**Output:**
+```
+Hello, Alice!
+Goodbye, World!
+```
+
+## How It Works
+
+Functions return a `FunctionReturn` dataclass instance with three attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `returned_values` | `dict[str, Any]` | Values to store in the shared environment |
+| `next_function_to_call` | `str \| None` | Name of the next function to execute, or `None` to stop (default: `None`) |
+| `arg_env_mapping` | `dict[str, str]` | Mapping of parameter names to environment variable keys (default: auto-mapped from `returned_values` keys) |
+
+**Key Feature**: If `arg_env_mapping` is not specified, it automatically maps each key in `returned_values` to itself. For example, `{"counter": 5}` automatically creates `{"counter": "counter"}` mapping.
+
+The engine maintains a shared environment where functions can store and retrieve values across calls.
+
+## Examples
+
+### Using the @register Decorator
+
+The `@register` decorator provides a cleaner way to register functions:
+
+```python
+from iterativerecursion import IterativeRecursionEngine, FunctionReturn
+
+engine = IterativeRecursionEngine()
+
+@engine.register
+def greet(name: str) -> FunctionReturn:
+    print(f"Hello, {name}!")
+    return FunctionReturn(
+        returned_values={"next_name": "World"},
+        next_function_to_call="farewell",
+        arg_env_mapping={"name": "next_name"}
+    )
+
+@engine.register
+def farewell(name: str) -> FunctionReturn:
+    print(f"Goodbye, {name}!")
+    return FunctionReturn(
+        returned_values={}
+    )
+
+# Start execution and get final state
+result = engine.start_function_caller(
+    next_function_to_call="greet",
+    environment_variables={"initial_name": "Alice"},
+    arg_env_mapping={"name": "initial_name"}
+)
+```
+
+### Factorial Calculation
+
+```python
+from iterativerecursion import IterativeRecursionEngine, FunctionReturn
+
+def factorial_step(n: int, accumulator: int) -> FunctionReturn:
+    if n <= 1:
+        return FunctionReturn(
+            returned_values={"result": accumulator}
+        )
+    # Auto-mapping: {"n": n-1, "accumulator": ...} automatically maps to itself
+    return FunctionReturn(
+        returned_values={
+            "n": n - 1,
+            "accumulator": accumulator * n
+        },
+        next_function_to_call="factorial_step"
+    )
+
+engine = IterativeRecursionEngine()
+engine.add_function(factorial_step)
+engine.start_function_caller(
+    next_function_to_call="factorial_step",
+    environment_variables={"n": 5, "accumulator": 1},
+    arg_env_mapping={"n": "n", "accumulator": "accumulator"}
+)
+
+print(f"5! = {engine.environment_variables['result']}")  # Output: 5! = 120
+```
+
+### Fibonacci Sequence (tail-recursive / iterative form)
+
+```python
+from iterativerecursion import IterativeRecursionEngine, FunctionReturn
+
+def fibonacci(n: int, a: int, b: int) -> FunctionReturn:
+    if n == 0:
+        return FunctionReturn(
+            returned_values={"result": a}
+        )
+    # Auto-mapping handles {"n": "n", "a": "a", "b": "b"} automatically
+    return FunctionReturn(
+        returned_values={
+            "n": n - 1,
+            "a": b,
+            "b": a + b
+        },
+        next_function_to_call="fibonacci"
+    )
+
+engine = IterativeRecursionEngine()
+engine.add_function(fibonacci)
+engine.start_function_caller(
+    next_function_to_call="fibonacci",
+    environment_variables={"n": 10, "a": 0, "b": 1},
+    arg_env_mapping={"n": "n", "a": "a", "b": "b"}
+)
+
+print(f"Fibonacci(10) = {engine.environment_variables['result']}")  # Output: 55
+```
+
+### Preventing Infinite Loops
+
+Use the `max_iterations` parameter to prevent runaway execution:
+
+```python
+from iterativerecursion import IterativeRecursionEngine, FunctionReturn
+
+def infinite_loop(counter: int) -> FunctionReturn:
+    print(f"Iteration: {counter}")
+    # Auto-mapping: no need for {"counter": "counter"}
+    return FunctionReturn(
+        returned_values={"counter": counter + 1},
+        next_function_to_call="infinite_loop"
+    )
+
+engine = IterativeRecursionEngine()
+engine.add_function(infinite_loop)
+
+try:
+    engine.start_function_caller(
+        next_function_to_call="infinite_loop",
+        environment_variables={"counter": 0},
+        arg_env_mapping={"counter": "counter"},
+        max_iterations=10  # Safety limit
+    )
+except RuntimeError as e:
+    print(f"Caught: {e}")
+    # Output: Caught: Maximum iteration limit (10) reached...
+```
+
+## API Reference
+
+### `IterativeRecursionEngine`
+
+The main execution engine for iterative recursion.
+
+#### Methods
+
+##### `__init__()`
+Creates a new engine instance.
+
+```python
+engine = IterativeRecursionEngine()
+```
+
+##### `add_function(function)`
+Registers a function with the engine.
+
+- **Parameters**: `function` - A callable that returns `FunctionReturn`
+- **Returns**: None
+
+```python
+engine.add_function(my_function)
+```
+
+##### `register(function)`
+Decorator to register a function with the engine. Alternative to `add_function()`.
+
+- **Parameters**: `function` - A callable that returns `FunctionReturn`
+- **Returns**: The same function (for chaining)
+
+```python
+@engine.register
+def my_function(x: int) -> FunctionReturn:
+    return FunctionReturn(
+        returned_values={"result": x * 2}
+    )
+```
+
+##### `add_environment_variables(variables: dict[str, Any])`
+Adds or updates variables in the shared environment.
+
+- **Parameters**: `variables` - Dictionary of variable names and values
+- **Returns**: None
+
+```python
+engine.add_environment_variables({"x": 10, "y": 20})
+```
+
+##### `start_function_caller(next_function_to_call, environment_variables, arg_env_mapping, max_iterations=None)`
+Begins executing functions starting from the specified function.
+
+- **Parameters**:
+  - `next_function_to_call` (str): Name of the first function to call
+  - `environment_variables` (dict[str, Any]): Initial environment variables
+  - `arg_env_mapping` (dict[str, str]): Parameter mapping for first function
+  - `max_iterations` (int | None): Maximum iterations allowed (default: None/unlimited)
+- **Returns**: `dict[str, Any]` - Final state of environment variables after execution
+- **Raises**:
+  - `KeyError`: If function not found or environment variable missing
+  - `RuntimeError`: If `max_iterations` limit is reached
+  - `ValueError`: If function returns invalid structure
+  - `TypeError`: If function return has wrong types
+
+```python
+result = engine.start_function_caller(
+    next_function_to_call="start_func",
+    environment_variables={"value": 42},
+    arg_env_mapping={"param": "value"},
+    max_iterations=1000
+)
+# Access final state directly from result
+print(result["some_value"])
+```
+
+#### Attributes
+
+- `functions_dict` (dict): Registry of available functions
+- `environment_variables` (dict): Shared state accessible to all functions
+
+### Type Definitions
+
+#### `FunctionReturn`
+Dataclass defining the required return structure for functions.
+
+```python
+@dataclass
+class FunctionReturn:
+    returned_values: dict[str, Any]
+    next_function_to_call: str | None = None
+    arg_env_mapping: dict[str, str] = field(default_factory=dict)
+```
+
+**Auto-mapping feature**: If `arg_env_mapping` is not provided, it automatically maps each key in `returned_values` to itself. This means you rarely need to specify `arg_env_mapping` explicitly.
+
+#### `VarsDict`
+Type alias for variable dictionaries.
+
+```python
+VarsDict = dict[str, Any]
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```
+
+### Test Coverage
+
+The test suite includes:
+- Basic function chaining
+- Environment variable management
+- Error handling and validation
+- Runtime validation of return structures
+- Iteration limits
+- Decorator API (`@register`)
+- Return value access
+- Improved error messages
+- Complex scenarios (factorial, state machines)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Carlos A. Planchón - [GitHub](https://github.com/carlosplanchon/iterativerecursion)
+
+## Acknowledgments
+
+This module was created as both a practical solution for deep recursion scenarios and an exploration of alternative execution patterns in Python.

iterativerecursion-1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+iterativerecursion/__init__.py,sha256=wVsJOPN8Xoqx00tt01GU_7_sa2qPCEG2BDcNiCpuXr0,223
+iterativerecursion/iterativerecursion.py,sha256=IisVgzbFlBPRCVIPSuTbOc_-JwpRvIyMHBWW8BtqCEI,8942
+iterativerecursion-1.0.dist-info/licenses/LICENSE,sha256=dUqwRhq9nAYp-zfLbCuFB1d_dlg7PjxGZzNMPCTaa0c,1076
+iterativerecursion-1.0.dist-info/METADATA,sha256=jDKPqoSevkN5B1zCRpLG-ziYyQq5ojwZFO4yztdSJI4,12400
+iterativerecursion-1.0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+iterativerecursion-1.0.dist-info/top_level.txt,sha256=L5ILEUqI0znr68qbm6FwMljLGneyLq9u2yKG80o0q10,19
+iterativerecursion-1.0.dist-info/RECORD,,

iterativerecursion-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

iterativerecursion-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Carlos A. Planchón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iterativerecursion-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+iterativerecursion