diff --git a/docs/reference/effects.md b/docs/reference/effects.md index 9cdd1d76..04742c63 100644 --- a/docs/reference/effects.md +++ b/docs/reference/effects.md @@ -13,3 +13,28 @@ workflows; see [Use effect builders](../guides/effects) for an example. .. automodule:: expression.core.builder :members: ``` + +## Synchronous builder contract + +`Builder` interprets generators eagerly. Custom `bind` implementations must call +their continuation exactly once, synchronously. Skipping the continuation, calling +it more than once, or retaining it for later execution raises `RuntimeError`. +Built-in Option/Result failures still short-circuit through their existing iterator +protocol. The builder closes its generator on completion or failure, running its +`finally` blocks and context-manager cleanup. + +Builder-hook exceptions propagate, including `StopIteration`; only generator +exhaustion counts as normal completion. `zero()` is used for empty computations, +not as an initial accumulator for computations that produce values. + +For compatibility, a generator ending with `return None` or falling off its end +retains its last yielded result. An empty body uses `zero()`. An explicit `yield +None` produces a successful value. `yield from Some(value)` and `yield from +Ok(value)` unwrap through Python's iterator protocol; they are not general F# +`Bind` operations. Failure uses `EffectError`, so a broad `except Exception` inside +the body can intercept it. + +The current `delay` hook receives an already computed step, and sequence builders +are eager. Deferred, reusable, and branching computations are outside this +interpreter's contract. These rules describe synchronous `Builder`; `AsyncBuilder` +has a separate implementation. diff --git a/expression/core/builder.py b/expression/core/builder.py index e629c306..10f8cb60 100644 --- a/expression/core/builder.py +++ b/expression/core/builder.py @@ -1,6 +1,7 @@ import inspect from abc import ABC from collections.abc import Callable, Generator +from dataclasses import dataclass from functools import wraps from typing import Any, Generic, TypeVar, cast @@ -15,17 +16,33 @@ class BuilderState(Generic[_T]): - """Encapsulates the state of a builder computation.""" + """Legacy computation state, retained for import compatibility.""" - def __init__(self): + def __init__(self) -> None: self.is_done = False -class Builder(Generic[_T, _M], ABC): # Corrected Generic definition - """Effect builder.""" +@dataclass(frozen=True) +class _Produced(Generic[_M]): + value: _M + is_terminal: bool = False + + +@dataclass(frozen=True) +class _Completed: + pass + + +class Builder(Generic[_T, _M], ABC): + """Eager generator effect builder. + + Each bind must invoke its continuation exactly once, synchronously. + Deferred and branching effects require a different execution model. + The builder owns the generator and closes it when execution exits. + """ # Required methods - def bind(self, xs: _M, fn: Callable[[_T], _M]) -> _M: # Use concrete types for Callable input and output + def bind(self, xs: _M, fn: Callable[[_T], _M]) -> _M: raise NotImplementedError("Builder does not implement a `bind` method") def return_(self, x: _T) -> _M: @@ -62,27 +79,66 @@ def run(self, computation: _M) -> _M: return computation # Internal implementation - def _send( - self, - gen: Generator[Any, Any, Any], - state: BuilderState[_T], # Use BuilderState - value: _T, - ) -> _M: + def _send(self, gen: Generator[Any, Any, Any], value: Any) -> _Produced[_M] | _Completed: + # Only generator advancement may signal completion or effect failure. + # Exceptions from builder hooks must propagate unchanged. try: yielded = gen.send(value) - return self.return_(yielded) except EffectError as error: - # Effect errors (Nothing, Error, etc) short circuits - state.is_done = True - return self.return_from(cast("_M", error.args[0])) + return _Produced(self.return_from(cast("_M", error.args[0])), is_terminal=True) except StopIteration as ex: - state.is_done = True - - # Return of a value in the generator produces StopIteration with a value - if ex.value is not None: - return self.return_(ex.value) + if ex.value is None: + return _Completed() + return _Produced(self.return_(ex.value), is_terminal=True) + return _Produced(self.return_(yielded)) + + def _advance(self, gen: Generator[Any, Any, Any], current: _M) -> tuple[_M, _Produced[_M] | _Completed]: + """Perform one bind while enforcing ownership of its continuation.""" + active = True + called = False + step: _Produced[_M] | _Completed = _Completed() + + def binder(sent: Any) -> _M: + nonlocal called, step + if not active or called: + raise RuntimeError("Builder requires a synchronous, single-use bind continuation") + called = True + step = self._send(gen, sent) + if isinstance(step, _Completed): + return current + produced = step.value + return self.delay(lambda: produced) - raise # Raise StopIteration with no value + try: + bound = self.bind(current, binder) + finally: + active = False + if not called: + raise RuntimeError("Builder.bind must invoke its continuation exactly once synchronously") + return bound, step + + def _evaluate_generator(self, gen: Generator[Any, Any, Any]) -> _M: + """Accumulate eager steps without growing the Python call stack.""" + initial = self._send(gen, None) + if isinstance(initial, _Completed): + return self.zero() + + result = value = self.delay(lambda: initial.value) + terminal = initial.is_terminal + while not terminal: + value, step = self._advance(gen, value) + if isinstance(step, _Completed): + break + result = self.combine(result, value) + terminal = step.is_terminal + return result + + def _run_generator(self, gen: Generator[Any, Any, Any]) -> _M: + """Own generator cleanup through evaluation and the final run hook.""" + try: + return self.run(self._evaluate_generator(gen)) + finally: + gen.close() def __call__( self, @@ -111,28 +167,6 @@ def wrapper(*args: _P.args, **kw: _P.kwargs) -> _M: return self.run(self.zero()) return self.run(self.return_(result_value)) - gen = cast("Generator[Any, Any, Any]", body) - state = BuilderState[_T]() # Initialize BuilderState - result: _M = self.zero() # Initialize result - value: _M - - def binder(value: Any) -> _M: - ret = self._send(gen, state, value) # Pass state to _send - return self.delay(lambda: ret) # Delay every bind call - - try: - # Initialize co-routine with None to start the generator and get the - # first value - result = value = binder(None) - - while not state.is_done: # Loop until coroutine is exhausted - value: _M = self.bind(value, binder) # Send value to coroutine - result = self.combine(result, value) # Combine previous result with new value - - except StopIteration: - # This will happens if the generator exits by returning None - pass - - return self.run(result) # Run the result + return self._run_generator(cast("Generator[Any, Any, Any]", body)) return wrapper diff --git a/tests/test_builder.py b/tests/test_builder.py new file mode 100644 index 00000000..138f647d --- /dev/null +++ b/tests/test_builder.py @@ -0,0 +1,136 @@ +"""Contracts for the eager generator interpreter, independent of built-in effects.""" + +from collections.abc import Callable +from typing import NoReturn + +import pytest + +from expression.core import Builder + + +class IdentityBuilder(Builder[int, int]): + def bind(self, xs: int, fn: Callable[[int], int]) -> int: + return fn(xs) + + def return_(self, x: int) -> int: + return x + + def return_from(self, xs: int) -> int: + return xs + + def combine(self, xs: int, ys: int) -> int: + return ys + + def zero(self) -> int: + return 0 + + +@pytest.mark.parametrize("hook", ["bind", "return_", "return_from", "combine", "delay", "run", "zero"]) +def test_hook_stop_iteration_propagates(hook: str): + from expression.core import EffectError + + builder = IdentityBuilder() + error = StopIteration("hook failure") + + def fail(*args: object) -> NoReturn: + raise error + + setattr(builder, hook, fail) + + @builder + def computation(): + if hook == "zero": + return + if hook == "return_from": + raise EffectError(1) + yield 1 + yield 2 + + with pytest.raises(StopIteration) as raised: + computation() + assert raised.value is error + + +@pytest.mark.parametrize("mode", ["skip", "twice", "raise"]) +def test_invalid_bind_closes_generator(mode: str): + closed: list[bool] = [] + resumed: list[int] = [] + + class InvalidBuilder(IdentityBuilder): + def bind(self, xs: int, fn: Callable[[int], int]) -> int: + if mode == "skip": + return xs + if mode == "raise": + raise RuntimeError("hook failure") + fn(xs) + return fn(xs) + + @InvalidBuilder() + def computation(): + try: + yield 1 + resumed.append(1) + yield 2 + resumed.append(2) + finally: + closed.append(True) + + with pytest.raises(RuntimeError): + computation() + assert closed == [True] + assert resumed == ([1] if mode == "twice" else []) + + +def test_retained_continuation_cannot_resume_later_iteration(): + callbacks: list[Callable[[int], int]] = [] + + class RetainingBuilder(IdentityBuilder): + def bind(self, xs: int, fn: Callable[[int], int]) -> int: + callbacks.append(fn) + if len(callbacks) == 2: + callbacks[0](xs) + return fn(xs) + + @RetainingBuilder() + def computation(): + yield 1 + yield 2 + return 3 + + with pytest.raises(RuntimeError, match="single-use"): + computation() + with pytest.raises(RuntimeError, match="single-use"): + callbacks[-1](4) + + +def test_generator_runtime_error_is_not_completion(): + @IdentityBuilder() + def computation(): + yield 1 + raise StopIteration("body bug") + + with pytest.raises(RuntimeError, match="generator raised StopIteration"): + computation() + + +def test_many_steps_remain_stack_safe(): + @IdentityBuilder() + def computation(): + for value in range(20_000): # noqa: UP028 - exercise individual send/yield steps + yield value + return 42 + + assert computation() == 42 + + +def test_zero_only_needed_for_empty_computation(): + class NonemptyBuilder(IdentityBuilder): + def zero(self): + raise AssertionError("zero is not a seed") + + @NonemptyBuilder() + def computation(): + yield 1 + return 2 + + assert computation() == 2