Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/reference/effects.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
122 changes: 78 additions & 44 deletions expression/core/builder.py
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
136 changes: 136 additions & 0 deletions tests/test_builder.py
Original file line number Diff line number Diff line change
@@ -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
Loading