Add async_option

Author: dbrattli

README.py

@@ -145,6 +145,8 @@
   - **seq** - a world for working with sequences.
   - **async_result** - an asynchronous error handling world for working
     with asynchronous result values.
+  - **async_option** - an asynchronous optional world for working with
+    asynchronous optional values.
 - **Mailbox Processor**: for lock free programming using the [Actor
   model](https://en.wikipedia.org/wiki/Actor_model).
 - **Cancellation Token**: for cancellation of asynchronous (and
@@ -536,6 +538,73 @@ async def outer() -> AsyncGenerator[int, int]:
 pinned to `Exception` i.e., `AsyncResult[TSource, Exception]`.
 """
 
+# %% [markdown]
+"""
+### AsyncOption
+
+The `AsyncOption[T]` type is the asynchronous version of `Option`. It allows you to
+compose asynchronous operations that may return an optional value, using the Option type.
+This is particularly useful for handling optional values in asynchronous code, such as
+API calls that might not return a value, database queries that might not find a record,
+or any other I/O-bound tasks that might not produce a meaningful result.
+
+Similar to the `Option` effect, AsyncOption enables short-circuiting but for asynchronous
+operations. If any part of the function yields `Nothing`, the function is short-circuited
+and the following statements will never be executed.
+"""
+
+# %%
+from collections.abc import AsyncGenerator
+
+from expression import Nothing, Some, effect
+
+
+@effect.async_option[int]()
+async def fn_option() -> AsyncGenerator[int, int]:
+    x: int = yield 42  # Regular value
+    y: int = yield await Some(43)  # Awaitable Some value
+
+    # Short-circuit if condition is met
+    if x + y > 80:
+        z: int = yield await Nothing  # This will short-circuit
+    else:
+        z: int = yield 44
+
+    yield x + y + z  # Final value
+
+
+# This would be run in an async context
+# result = await fn_option()
+# assert result is Nothing
+
+# %% [markdown]
+"""
+AsyncOption works well with other async functions and can be nested:
+"""
+
+
+# %%
+@effect.async_option[int]()
+async def inner_option(x: int) -> AsyncGenerator[int, int]:
+    y: int = yield x + 1
+    yield y + 1  # Final value is y + 1
+
+
+@effect.async_option[int]()
+async def outer_option() -> AsyncGenerator[int, int]:
+    x: int = yield 40
+
+    # Call inner and await its result
+    inner_result = await inner_option(x)
+    y: int = yield await inner_result
+
+    yield y  # Final value is y
+
+
+# This would be run in an async context
+# result = await outer_option()
+# assert result == Some(42)  # 40 -> 41 -> 42
+
 # %% [markdown]
 """
 ### Sequence

expression/core/option.py

@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 import builtins
-from collections.abc import Callable, Generator, Iterable
+from collections.abc import Awaitable, Callable, Generator, Iterable
 from typing import TYPE_CHECKING, Any, Literal, TypeGuard, TypeVar, cast, get_args, get_origin
 
 from typing_extensions import TypeVarTuple, Unpack
@@ -42,6 +42,7 @@
 @tagged_union(frozen=True, order=True)
 class Option(
     Iterable[_TSourceOut],
+    Awaitable[_TSourceOut],
     PipeMixin,
 ):
     """Option class."""
@@ -296,6 +297,16 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return self.__str__()
 
+    def __await__(self) -> Generator[_TSourceOut, _TSourceOut, _TSourceOut]:
+        """Make Option awaitable by delegating to __iter__."""
+        match self:
+            case Option(tag="some", some=value):
+                return value
+            case _:
+                raise EffectError(self)
+
+        yield None
+
     @classmethod
     def __get_pydantic_core_schema__(cls, source_type: Any, handler: GetCoreSchemaHandler) -> CoreSchema:
         from pydantic import ValidatorFunctionWrapHandler

expression/effect/__init__.py

@@ -1,5 +1,6 @@
 """A collection of computational expression effects."""
 
+from .async_option import AsyncOptionBuilder as async_option
 from .async_result import AsyncResultBuilder as async_result
 from .async_result import AsyncTryBuilder as async_try
 from .option import OptionBuilder as option
@@ -11,4 +12,4 @@
 seq = seq_builder
 
 
-__all__ = ["async_result", "async_try", "option", "result", "seq", "try_"]
+__all__ = ["async_option", "async_result", "async_try", "option", "result", "seq", "try_"]

expression/effect/async_option.py

@@ -0,0 +1,137 @@
+"""AsyncOption builder module.
+
+The AsyncOption builder allows for composing asynchronous operations that
+may return an optional value, using the Option type. It's similar to the Option builder but
+works with async operations.
+"""
+
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar
+
+from expression.core import Nothing, Option, Some
+from expression.core.async_builder import AsyncBuilder
+
+
+_TSource = TypeVar("_TSource")
+_TResult = TypeVar("_TResult")
+_P = ParamSpec("_P")
+
+
+class AsyncOptionBuilder(AsyncBuilder[_TSource, Option[Any]]):
+    """AsyncOption builder.
+
+    The AsyncOption builder allows for composing asynchronous operations that
+    may return an optional value, using the Option type.
+    """
+
+    async def bind(
+        self,
+        xs: Option[_TSource],
+        fn: Callable[[Any], Awaitable[Option[_TResult]]],
+    ) -> Option[_TResult]:
+        """Bind a function to an async option value.
+
+        In F# computation expressions, this corresponds to ``let!`` and enables
+        sequencing of computations.
+
+        Args:
+            xs: The async 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
+        """
+        match xs:
+            case Option(tag="some", some=value):
+                return await fn(value)
+            case _:
+                return Nothing
+
+    async def return_(self, x: _TSource) -> Option[_TSource]:
+        """Wrap a value in an async 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)
+
+    async def return_from(self, xs: Option[_TSource]) -> Option[_TSource]:
+        """Return an async option value directly.
+
+        In F# computation expressions, this corresponds to ``return!`` and allows
+        returning an already wrapped value.
+
+        Args:
+            xs: The async option value to return
+
+        Returns:
+            The async option value unchanged
+        """
+        return xs
+
+    async def combine(self, xs: Option[_TSource], ys: Option[_TSource]) -> Option[_TSource]:
+        """Combine two async option computations.
+
+        In F# computation expressions, this enables sequencing multiple
+        expressions where we only care about the final result.
+
+        Args:
+            xs: First async option computation
+            ys: Second async option computation
+
+        Returns:
+            The second computation if first is Some, otherwise Nothing
+        """
+        match xs:
+            case Option(tag="some"):
+                return ys
+            case _:
+                return Nothing
+
+    async def zero(self) -> Option[Any]:
+        """Return the zero value for async options.
+
+        In F# computation expressions, this is used when no value is returned,
+        corresponding to None in F#.
+
+        Returns:
+            Nothing
+        """
+        return Nothing
+
+    async def delay(self, fn: Callable[[], Option[_TSource]]) -> Option[_TSource]:
+        """Delay the computation.
+
+        Default implementation is to return the result of the function.
+        """
+        return fn()
+
+    async def run(self, computation: Option[_TSource]) -> Option[_TSource]:
+        """Run a computation.
+
+        Default implementation is to return the computation as is.
+        """
+        return computation
+
+    def __call__(
+        self,
+        fn: Callable[
+            _P,
+            AsyncGenerator[_TSource, _TSource] | AsyncGenerator[_TSource, None],
+        ],
+    ) -> Callable[_P, Awaitable[Option[_TSource]]]:
+        """The builder decorator."""
+        return super().__call__(fn)
+
+
+# Create singleton instance
+async_option: AsyncOptionBuilder[Any] = AsyncOptionBuilder()
+
+
+__all__ = ["AsyncOptionBuilder", "async_option"]