iterativerecursion

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.

Installation

Using uv

uv add iterativerecursion

Using pip

pip install iterativerecursion

Quick Start

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:

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:

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

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)

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:

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.

engine = IterativeRecursionEngine()

add_function(function)

Registers a function with the engine.

• Parameters: function - A callable that returns FunctionReturn
• Returns: None

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)

@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

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 | None): Name of the first function to call. Pass None to terminate immediately after recording environment_variables.
  • 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

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.

@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.

VarsDict = dict[str, Any]

Development

Running Tests

# 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 file for details.

Author

Carlos A. Planchón - GitHub

Acknowledgments

This module was created as both a practical solution for deep recursion scenarios and an exploration of alternative execution patterns in Python.