Add better testing for builder code (#245)

* Add better testing for builder code

Author: dbrattli

expression/core/builder.py

@@ -38,12 +38,34 @@ def zero(self) -> _TOuter:
         raise NotImplementedError("Builder does not implement a zero method")
 
     def delay(self, fn: Callable[[], _TOuter]) -> _TOuter:
-        """Default implementation evaluates the given function."""
+        """Delay the computation.
+
+        In F# computation expressions, delay wraps the entire computation to ensure
+        it is not evaluated until run. This enables proper sequencing of effects
+        and lazy evaluation.
+
+        Args:
+            fn: The computation to delay
+
+        Returns:
+            The delayed computation
+        """
         return fn()
 
-    def run(self, xs: _TOuter) -> _TOuter:
-        """Default implementation assumes the result is already evaluated."""
-        return xs
+    def run(self, computation: _TOuter) -> _TOuter:
+        """Run a computation.
+
+        Forces evaluation of a delayed computation. In F# computation expressions,
+        run is called at the end to evaluate the entire computation that was
+        wrapped in delay.
+
+        Args:
+            computation: The computation to run
+
+        Returns:
+            The evaluated result
+        """
+        return computation
 
     def _send(
         self,
@@ -126,6 +148,7 @@ def binder(value: Any) -> _TOuter:
             if result is None:
                 result = self.zero()
 
+            # Run the computation at the end
             return self.run(result)
 
         return wrapper

expression/core/option.py

@@ -177,8 +177,8 @@ def filter(self, predicate: Callable[[_TSourceOut], bool]) -> Option[_TSourceOut
     def to_list(self) -> list[_TSourceOut]:
         """Convert option to list."""
         match self:
-            case Option(tag="some", some=some):
-                return [some]
+            case Option(tag="some", some=value):
+                return [value]
             case _:
                 return []
 
@@ -188,8 +188,8 @@ def to_seq(self) -> Seq[_TSourceOut]:
         from expression.collections.seq import Seq
 
         match self:
-            case Option(tag="some", some=some):
-                return Seq[_TSourceOut].of(some)
+            case Option(tag="some", some=value):
+                return Seq[_TSourceOut].of(value)
             case _:
                 return Seq()
 

expression/core/typing.py

@@ -5,7 +5,6 @@
 from typing import Any, Protocol, TypeVar, get_origin
 
 
-_T = TypeVar("_T")
 _T_co = TypeVar("_T_co", covariant=True)
 
 _Base = TypeVar("_Base")

expression/effect/option.py

@@ -13,20 +13,88 @@
 
 class OptionBuilder(Builder[_TSource, Option[Any]]):
     def bind(self, xs: Option[_TSource], fn: Callable[[_TSource], Option[_TResult]]) -> Option[_TResult]:
+        """Bind a function to an option value.
+
+        In F# computation expressions, this corresponds to let! and enables
+        sequencing of computations.
+
+        Args:
+            xs: The option value to bind
+            fn: The function to apply to the value if Some
+
+        Returns:
+            The result of applying fn to the value if Some, otherwise Nothing
+        """
         return option.bind(fn)(xs)
 
     def return_(self, x: _TSource) -> Option[_TSource]:
+        """Wrap a value in an option.
+
+        In F# computation expressions, this corresponds to return and lifts
+        a value into the option context.
+
+        Args:
+            x: The value to wrap
+
+        Returns:
+            Some containing the value
+        """
         return Some(x)
 
     def return_from(self, xs: Option[_TSource]) -> Option[_TSource]:
+        """Return an option value directly.
+
+        In F# computation expressions, this corresponds to return! and allows
+        returning an already wrapped value.
+
+        Args:
+            xs: The option value to return
+
+        Returns:
+            The option value unchanged
+        """
         return xs
 
     def combine(self, xs: Option[_TSource], ys: Option[_TSource]) -> Option[_TSource]:
+        """Combine two option computations.
+
+        In F# computation expressions, this enables sequencing multiple
+        expressions where we only care about the final result.
+
+        Args:
+            xs: First option computation
+            ys: Second option computation
+
+        Returns:
+            The second computation if first is Some, otherwise Nothing
+        """
         return xs.bind(lambda _: ys)
 
     def zero(self) -> Option[_TSource]:
+        """Return the zero value for options.
+
+        In F# computation expressions, this is used when no value is returned,
+        corresponding to None in F#.
+
+        Returns:
+            Nothing
+        """
         return Nothing
 
+    def delay(self, fn: Callable[[], Option[_TSource]]) -> Option[_TSource]:
+        """Delay an option computation.
+
+        In F# computation expressions, delay ensures proper sequencing of effects
+        by controlling when computations are evaluated.
+
+        Args:
+            fn: The computation to delay
+
+        Returns:
+            The result of evaluating the computation
+        """
+        return fn()
+
     def __call__(
         self,  # Ignored self parameter
         fn: Callable[

tests/test_option.py

@@ -1,7 +1,6 @@
-from collections.abc import Callable, Generator
+from collections.abc import Callable
 from typing import Any, Annotated
 
-import pytest
 from hypothesis import given  # type: ignore
 from hypothesis import strategies as st
 from pydantic import BaseModel, Field, GetCoreSchemaHandler
@@ -14,14 +13,12 @@
     Option,
     Result,
     Some,
-    effect,
     option,
     pipe,
     pipe2,
 )
 from expression.core.option import Nothing, Option, Some
 from expression.extra.option import pipeline
-from tests.utils import CustomException
 
 
 def test_option_some():
@@ -53,11 +50,19 @@ def test_option_some_match_fluent():
         case _:
             assert False
 
+def test_option_some_iterate_to_list():
+    xs = Some(42)
+
+    for x in xs.to_list():
+        assert x == 42
+        break
+    else:
+        assert False
 
 def test_option_some_iterate():
     xs = Some(42)
 
-    for x in option.to_list(xs):
+    for x in xs:
         assert x == 42
         break
     else:
@@ -425,150 +430,6 @@ def test_option_to_optional_nothing():
     assert xs is None
 
 
-def test_option_builder_zero():
-    @effect.option[int]()
-    def fn():
-        while False:
-            yield
-
-    xs = fn()
-    assert xs is Nothing
-
-
-def test_option_builder_yield_value():
-    @effect.option[int]()
-    def fn():
-        yield 42
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == 42
-        case _:
-            assert False
-
-
-def test_option_builder_yield_value_async():
-    @effect.option[int]()
-    def fn():
-        yield 42
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == 42
-        case _:
-            assert False
-
-
-def test_option_builder_yield_some_wrapped():
-    @effect.option[Option[int]]()
-    def fn() -> Generator[Option[int], Option[int], Option[int]]:
-        x: Option[int] = yield Some(42)
-        return x
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == Some(42)
-        case _:
-            assert False
-
-
-def test_option_builder_return_some():
-    @effect.option[int]()
-    def fn() -> Generator[int, int, int]:
-        x: int = yield 42
-        return x
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == 42
-        case _:
-            assert False
-
-
-def test_option_builder_return_nothing_wrapped():
-    @effect.option[Option[int]]()
-    def fn():
-        return Nothing
-        yield
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value is Nothing
-        case _:
-            assert False
-
-
-def test_option_builder_yield_from_some():
-    @effect.option[int]()
-    def fn() -> Generator[int, int, int]:
-        x = yield from Some(42)
-        return x + 1
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == 43
-        case _:
-            assert False
-
-
-def test_option_builder_yield_from_none():
-    @effect.option[int]()
-    def fn() -> Generator[int, int, int]:
-        x: int
-        x = yield from Nothing
-        return x
-
-    xs = fn()
-    assert xs is Nothing
-
-
-def test_option_builder_multiple_some():
-    @effect.option[int]()
-    def fn() -> Generator[int, int, int]:
-        x: int = yield 42
-        y = yield from Some(43)
-
-        return x + y
-
-    xs = fn()
-    match xs:
-        case Option(tag="some", some=value):
-            assert value == 85
-        case _:
-            assert False
-
-
-def test_option_builder_none_short_circuits():
-    @effect.option[int]()
-    def fn() -> Generator[int, int, int]:
-        x: int = yield from Nothing
-        y = yield from Some(43)
-
-        return x + y
-
-    xs = fn()
-    assert xs is Nothing
-
-
-def test_option_builder_throws():
-    error = "do'h"
-
-    @effect.option()
-    def fn():
-        raise CustomException(error)
-        yield
-
-    with pytest.raises(CustomException) as ex:
-        fn()
-
-    assert ex.value.message == error
-
 
 def test_pipeline_none():
     hn = pipeline()