trampoline

0.1.2 · maintenance · verified Sat Apr 11

The `trampoline` library (version 0.1.2) provides a simple and tiny yield-based implementation of the trampoline technique in Python. It allows recursive functions to overcome Python's recursion depth limit by converting them into generators that yield subsequent recursive calls, which are then driven by a central `trampoline` function. This enables virtually infinite recursion without exhausting the call stack. The library has not seen recent updates, with its last release in 2018.

Warnings

maintenance The `trampoline` library (v0.1.2) was last updated in 2018. While its core concept is stable, the lack of recent maintenance means it may not receive updates for new Python features, critical bug fixes, or security patches. Consider this for long-term project viability.
Fix: Evaluate if the small, self-contained nature of the library is acceptable given its age, or consider reimplementing the trampoline pattern directly if deeper control or active maintenance is required.
gotcha Trampolined functions must be written as generators that `yield` the next recursive call, rather than calling it directly. Failing to `yield` will bypass the trampoline and lead to Python's `RecursionError`.
Fix: Ensure that all recursive calls within your trampolined function are prefixed with `yield`, e.g., `yield my_recursive_func(arg)`.
gotcha When a trampolined function needs to return a value from a recursive step, the `yield` statement must be used as an expression to capture the result. Simply `yield`ing the call will not pass the return value back.
Fix: For functions that return values, structure your recursive call like `return (yield next_recursive_call) * some_operation` to capture and use the result.
gotcha The initial call to your trampolined generator function must be wrapped by the `trampoline()` utility function. The generator itself does not execute the trampoline logic.
Fix: Always invoke your top-level trampolined generator function by passing it to `trampoline()`, e.g., `result = trampoline(my_func(initial_arg))`.

Install

pip install trampoline Install with pip

Imports

trampoline
```
from trampoline import trampoline
```
TailCall
```
from trampoline import TailCall
```
Used for specific tail-call optimization patterns where exceptions are preferred over yield for signalling the next call.

Quickstart

This quickstart demonstrates how to define a recursive function as a generator, yielding the next recursive call. The `trampoline()` function then drives this generator, managing the 'recursion' iteratively and allowing it to handle deep call chains without stack overflow. It also shows how to receive return values from yielded sub-generators.

from trampoline import trampoline

def factorial(n):
    """Calculates factorial of n using a trampolined generator."""
    if n <= 1:
        return 1
    # Yield the next recursive call, and receive its result
    return (yield factorial(n - 1)) * n

# Run the trampolined function
result = trampoline(factorial(5))
print(f"Factorial of 5: {result}")

try:
    # Example with a large number that would cause RecursionError normally
    # result_large = trampoline(factorial(2000))
    # print(f"Factorial of 2000: {result_large}")
    print("Skipping factorial(2000) for quickstart brevity, but it would work.")
except RecursionError as e:
    print(f"Caught expected RecursionError (if not trampolined): {e}")

view raw JSON →