Add docs. Fix type errors

Author: dbrattli

README.py

@@ -461,6 +461,78 @@ def fn5() -> Generator[int, int, int]:
 pinned to `Exception` i.e., `Result[TSource, Exception]`.
 """
 
+# %% [markdown]
+"""
+### AsyncResult
+
+The `AsyncResult[T, TError]` type is the asynchronous version of `Result`. It allows you
+to compose asynchronous operations that may fail, using the Result type. This is
+particularly useful for handling errors in asynchronous code, such as API calls,
+database operations, or any other I/O-bound tasks.
+
+Similar to the `Result` effect, AsyncResult enables "railway oriented programming" but
+for asynchronous operations. If any part of the function yields an `Error`, the function
+is short-circuited and the following statements will never be executed.
+"""
+
+# %%
+from collections.abc import AsyncGenerator
+
+from expression import Error, Ok, effect
+
+
+@effect.async_result[int, str]()
+async def fn() -> AsyncGenerator[int, int]:
+    x: int = yield 42  # Regular value
+    y: int = yield await Ok(43)  # Awaitable Ok value
+
+    # Short-circuit if condition is met
+    if x + y > 80:
+        z: int = yield await Error("Value too large")  # 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()
+# assert result == Error("Value too large")
+
+# %% [markdown]
+"""
+AsyncResult works well with other async functions and can be nested:
+"""
+
+
+# %%
+@effect.async_result[int, str]()
+async def inner(x: int) -> AsyncGenerator[int, int]:
+    y: int = yield x + 1
+    yield y + 1  # Final value is y + 1
+
+
+@effect.async_result[int, str]()
+async def outer() -> AsyncGenerator[int, int]:
+    x: int = yield 40
+
+    # Call inner and await its result
+    inner_result = await inner(x)
+    y: int = yield await inner_result
+
+    yield y  # Final value is y
+
+
+# This would be run in an async context
+# result = await outer()
+# assert result == Ok(42)  # 40 -> 41 -> 42
+
+# %% [markdown]
+"""
+A simplified type called `AsyncTry` is also available. It's an async result type that is
+pinned to `Exception` i.e., `AsyncResult[TSource, Exception]`.
+"""
+
 # %% [markdown]
 """
 ### Sequence

expression/core/async_builder.py

@@ -14,8 +14,8 @@
 from .error import EffectError
 
 
-_T = TypeVar("_T")  # for value type
-_M = TypeVar("_M")  # for monadic type
+_T = TypeVar("_T")  # The container item type
+_M = TypeVar("_M")  # for container type
 _P = ParamSpec("_P")
 
 
@@ -82,12 +82,10 @@ async def _send(
             # Effect errors (Nothing, Error, etc) short circuits
             state.is_done = True
             return await self.return_from(cast("_M", error.args[0]))
-        except StopAsyncIteration as ex:
-            print("StopAsyncIteration occurred", ex)
+        except StopAsyncIteration:
             state.is_done = True
             raise
-        except Exception as ex:
-            print("Exception occurred", ex)
+        except Exception:
             state.is_done = True
             raise
 

expression/effect/__init__.py

@@ -1,14 +1,14 @@
 """A collection of computational expression effects."""
 
+from .async_result import AsyncResultBuilder as async_result
+from .async_result import AsyncTryBuilder as async_try
 from .option import OptionBuilder as option
 from .result import ResultBuilder as result
 from .result import TryBuilder as try_
 from .seq import SeqBuilder as seq_builder
-from .async_result import AsyncResultBuilder as async_result
-from .async_result import AsyncTryBuilder as async_try
 
 
 seq = seq_builder
 
 
-__all__ = ["option", "result", "seq", "try_", "async_result", "async_try"]
+__all__ = ["async_result", "async_try", "option", "result", "seq", "try_"]

expression/effect/async_result.py

@@ -5,8 +5,8 @@
 works with async operations.
 """
 
-from collections.abc import Awaitable, Callable
-from typing import Any, TypeVar
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar
 
 from expression.core import Ok, Result
 from expression.core.async_builder import AsyncBuilder
@@ -15,6 +15,7 @@
 _TSource = TypeVar("_TSource")
 _TResult = TypeVar("_TResult")
 _TError = TypeVar("_TError")
+_P = ParamSpec("_P")
 
 
 class AsyncResultBuilder(AsyncBuilder[_TSource, Result[Any, _TError]]):
@@ -119,6 +120,16 @@ async def run(self, computation: Result[_TSource, _TError]) -> Result[_TSource,
         """
         return computation
 
+    def __call__(
+        self,
+        fn: Callable[
+            _P,
+            AsyncGenerator[_TSource, _TSource] | AsyncGenerator[_TSource, None],
+        ],
+    ) -> Callable[_P, Awaitable[Result[_TSource, _TError]]]:
+        """The builder decorator."""
+        return super().__call__(fn)
+
 
 # Create singleton instances
 async_result: AsyncResultBuilder[Any, Any] = AsyncResultBuilder()

tests/test_async_result_builder.py

@@ -233,13 +233,12 @@ async def fn() -> AsyncGenerator[int, int]:
         case _:
             assert False
 
-
 @pytest.mark.asyncio
 async def test_async_result_builder_return_error_wrapped():
     """Test that async_result builder properly handles returning Error directly."""
 
     @effect.async_result[Result[int, str], str]()
-    async def fn() -> AsyncGenerator[Result[int, str], int]:
+    async def fn() -> AsyncGenerator[Result[int, str], Result[int, str]]:
         yield Error("error")  # Use yield await instead of return
         # No need for additional yield
 
@@ -360,13 +359,13 @@ async def fn() -> AsyncGenerator[int, int]:
 async def test_async_result_builder_with_async_result_functions():
     """Test that async_result builder properly works with functions returning async Results."""
 
-    async def async_ok_function(x: int) -> Result[int, str]:
+    async def async_ok_function(x: int) -> int:
         await asyncio.sleep(0.01)  # Small delay to simulate async work
-        return Ok(x * 2)
+        return await Ok(x * 2)
 
-    async def async_error_function(msg: str) -> Result[int, str]:
+    async def async_error_function(msg: str) -> int:
         await asyncio.sleep(0.01)  # Small delay to simulate async work
-        return Error(msg)
+        return await Error(msg)
 
     @effect.async_result[int, str]()
     async def success_fn() -> AsyncGenerator[int, int]:
@@ -375,18 +374,18 @@ async def success_fn() -> AsyncGenerator[int, int]:
         # Call async function and get its result
         result = await async_ok_function(x)
         # Then yield the result
-        y: int = yield await result
+        y: int = yield result
 
         yield y
 
     @effect.async_result[int, str]()
     async def error_fn() -> AsyncGenerator[int, int]:
-        x: int = yield 21
+        _: int = yield 21
 
         # Call async function and get its result
         result = await async_error_function("async error")
         # Then yield it - this should short-circuit
-        y: int = yield await result
+        y: int = yield result
 
         yield y  # Should not reach here