diff --git a/docs/reference/pipe.md b/docs/reference/pipe.md index 0195e278..47b9eba5 100644 --- a/docs/reference/pipe.md +++ b/docs/reference/pipe.md @@ -5,4 +5,48 @@ ```{eval-rst} .. automodule:: expression.core.pipe :members: -``` \ No newline at end of file +``` + +## Asynchronous pipelines + +Use `apipe` to mix synchronous functions and coroutine-returning functions: + +```python +from expression import apipe + +async def increment(value: int) -> int: + return value + 1 + +async def example() -> str: + return await apipe(2, increment, lambda value: value * 3, str) +``` + +`apipe` starts when awaited and executes stages sequentially. It awaits a native +coroutine supplied as the initial value or returned by a stage once. Exceptions +and cancellation propagate, and later stages do not run. + +Other values pass through unchanged, including `Option` and `Result`, even though +these types implement `__await__`. Tasks, futures, and custom awaitables also pass +through unchanged: use an `async def` wrapper that explicitly awaits them when +you want their resolved values. The existing `pipe` never inserts awaits. + +For asynchronous Result mapping, use `expression.extra.async_result.bind`: + +```python +from expression import Ok, Result, apipe +from expression.extra import async_result + +async def increment(value: int) -> Result[int, str]: + return Ok(value + 1) + +async def example() -> Result[str, str]: + return await apipe(Ok(2), async_result.bind(increment), lambda value: value.map(str)) +``` + +`bind` skips the mapper on `Error`; plain `apipe` itself does not short-circuit +Result values. + +```{eval-rst} +.. automodule:: expression.core.apipe + :members: +``` diff --git a/expression/__init__.py b/expression/__init__.py index 7d49407b..f8e5fde8 100644 --- a/expression/__init__.py +++ b/expression/__init__.py @@ -29,6 +29,7 @@ TailCall, TailCallResult, Try, + apipe, case, compose, curry, @@ -84,6 +85,7 @@ "TailCallResult", "Try", "__version__", + "apipe", "case", "collections", "compose", diff --git a/expression/core/__init__.py b/expression/core/__init__.py index f9c981ed..6a04a9e6 100644 --- a/expression/core/__init__.py +++ b/expression/core/__init__.py @@ -1,6 +1,7 @@ """Core abstractions such as pipes, options and results.""" from . import aiotools, option, result, tagged_union +from .apipe import apipe from .builder import Builder from .compose import compose from .curry import curry, curry_flip, pipeable @@ -48,6 +49,7 @@ "TailCallResult", "Try", "aiotools", + "apipe", "case", "compose", "curry", diff --git a/expression/core/apipe.py b/expression/core/apipe.py new file mode 100644 index 00000000..23125a18 --- /dev/null +++ b/expression/core/apipe.py @@ -0,0 +1,161 @@ +"""Asynchronous pipe composition. + +The pipe handles both synchronous and asynchronous functions; if a function +returns a Coroutine, it is awaited before its result is passed to the next function. +""" + +import inspect +from collections.abc import Callable, Coroutine +from typing import Any, TypeVar, overload + + +_A = TypeVar("_A") +_B = TypeVar("_B") +_C = TypeVar("_C") +_D = TypeVar("_D") +_E = TypeVar("_E") +_F = TypeVar("_F") +_G = TypeVar("_G") +_H = TypeVar("_H") +_T = TypeVar("_T") +_J = TypeVar("_J") + +_X = TypeVar("_X") +_Y = TypeVar("_Y") + +SyncCallable = Callable[[_X], _Y] +AsyncCallable = Callable[[_X], Coroutine[Any, Any, _Y]] +SyncOrAsyncCallable = SyncCallable[_X, _Y] | AsyncCallable[_X, _Y] + + +@overload +async def apipe(value: Coroutine[Any, Any, _A] | _A, /) -> _A: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + /, +) -> _B: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + /, +) -> _C: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + /, +) -> _D: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + /, +) -> _E: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + fn5: SyncOrAsyncCallable[_E, _F], + /, +) -> _F: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + fn5: SyncOrAsyncCallable[_E, _F], + fn6: SyncOrAsyncCallable[_F, _G], + /, +) -> _G: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + fn5: SyncOrAsyncCallable[_E, _F], + fn6: SyncOrAsyncCallable[_F, _G], + fn7: SyncOrAsyncCallable[_G, _H], + /, +) -> _H: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + fn5: SyncOrAsyncCallable[_E, _F], + fn6: SyncOrAsyncCallable[_F, _G], + fn7: SyncOrAsyncCallable[_G, _H], + fn8: SyncOrAsyncCallable[_H, _T], + /, +) -> _T: ... + + +@overload +async def apipe( + value: Coroutine[Any, Any, _A] | _A, + fn1: SyncOrAsyncCallable[_A, _B], + fn2: SyncOrAsyncCallable[_B, _C], + fn3: SyncOrAsyncCallable[_C, _D], + fn4: SyncOrAsyncCallable[_D, _E], + fn5: SyncOrAsyncCallable[_E, _F], + fn6: SyncOrAsyncCallable[_F, _G], + fn7: SyncOrAsyncCallable[_G, _H], + fn8: SyncOrAsyncCallable[_H, _T], + fn9: SyncOrAsyncCallable[_T, _J], + /, +) -> _J: ... + + +async def apipe(value: Any, *functions: SyncOrAsyncCallable[Any, Any]) -> Any: + """Apply mixed synchronous and asynchronous stages sequentially. + + Await native coroutines in the initial value and each stage's output once. + Other values, including Option, Result, tasks, and futures, pass through + unchanged. Wrap other awaitables in an async function to resolve them. + Execution starts when the returned coroutine is awaited. Exceptions and + cancellation propagate without running subsequent stages. + """ + if inspect.iscoroutine(value): + value = await value + for function in functions: + value = function(value) + if inspect.iscoroutine(value): + value = await value + return value + + +__all__ = ["apipe"] diff --git a/expression/core/result.py b/expression/core/result.py index 8c3e8237..abfe74b1 100644 --- a/expression/core/result.py +++ b/expression/core/result.py @@ -418,6 +418,9 @@ def __call__(self, source: Ok[_A]) -> _R: ... @overload def __call__(self, source: Error[_F]) -> Error[_F]: ... + @overload + def __call__(self, source: Result[_A, _F]) -> _R | Error[_F]: ... + def __call__(self, source: Result[_A, _F]) -> _R | Error[_F]: return source.bind(self._mapper) diff --git a/expression/extra/__init__.py b/expression/extra/__init__.py index a0f725e5..d04158e8 100644 --- a/expression/extra/__init__.py +++ b/expression/extra/__init__.py @@ -4,7 +4,7 @@ functions. """ -from . import option, result +from . import async_result, option, result -__all__ = ["option", "result"] +__all__ = ["async_result", "option", "result"] diff --git a/expression/extra/async_result/__init__.py b/expression/extra/async_result/__init__.py new file mode 100644 index 00000000..379b69a9 --- /dev/null +++ b/expression/extra/async_result/__init__.py @@ -0,0 +1,6 @@ +"""Extra async_result functions.""" + +from .async_result import bind + + +__all__ = ["bind"] diff --git a/expression/extra/async_result/async_result.py b/expression/extra/async_result/async_result.py new file mode 100644 index 00000000..696d0f86 --- /dev/null +++ b/expression/extra/async_result/async_result.py @@ -0,0 +1,24 @@ +from collections.abc import Awaitable, Callable, Coroutine +from typing import Any, TypeVar + +from expression import Result +from expression.effect.async_result import async_result + + +_TSource = TypeVar("_TSource") +_TResult = TypeVar("_TResult") +_TError = TypeVar("_TError") + + +def bind( + mapper: Callable[[_TSource], Awaitable[Result[_TResult, _TError]]], +) -> Callable[[Result[_TSource, _TError]], Coroutine[Any, Any, Result[_TResult, _TError]]]: + """Apply an asynchronous mapper to Ok, preserving Error without calling it.""" + + async def wrapped(result: Result[_TSource, _TError]) -> Result[_TResult, _TError]: + return await async_result.bind(result, mapper) + + return wrapped + + +__all__ = ["bind"] diff --git a/tests/test_apipe.py b/tests/test_apipe.py new file mode 100644 index 00000000..88802769 --- /dev/null +++ b/tests/test_apipe.py @@ -0,0 +1,234 @@ +import asyncio +import sys +from collections.abc import Callable +from typing import Any, assert_type + +import pytest +from hypothesis import given +from hypothesis import strategies as st + +from expression import NOTHING, Error, Ok, Result, Some, apipe, pipe, result +from expression.extra import async_result + + +@given(st.integers()) +def test_pipe_id(x: int): + value = asyncio.run(apipe(x)) + assert value == x + + +@given(st.integers()) +def test_pipe_awaitable_only(x: int): + async def awaitable_value() -> int: + return x + + value = asyncio.run(apipe(awaitable_value())) + assert value == x + + +@given(st.integers()) +def test_pipe_fn(x: int): + async def gn(x: int) -> int: + return x + 1 + + value = asyncio.run(apipe(x, gn)) + assert value == asyncio.run(gn(x)) + + +@given(st.integers(), st.integers(), st.integers()) +def test_pipe_fn_gn(x: int, y: int, z: int): + fn: Callable[[int], int] = lambda x: x + z + + async def gn(x: int) -> int: + return x * y + + value = asyncio.run(apipe(x, fn, gn)) + + assert value == asyncio.run(gn(fn(x))) + + value = asyncio.run( + apipe( + x, + gn, + fn, + ) + ) + + assert value == fn(asyncio.run(gn(x))) + + +@given(st.integers(), st.integers(), st.integers()) +def test_pipe_async_result(x: int, y: int, z: int): + fn: Callable[[int], Result[int, str]] = lambda x: Ok(x + z) + + async def gn(x: int) -> Result[int, str]: + return Ok(x * y) + + value = asyncio.run( + apipe( + Ok(x), + result.bind(fn), + async_result.bind(gn), + ) + ) + + assert value == Ok((x + z) * y) + + value = asyncio.run( + apipe( + Ok(x), + async_result.bind(gn), + result.bind(fn), + ) + ) + + assert value == Ok((x * y) + z) + + +# Runtime boundaries and inference are part of the public contract. + + +@pytest.mark.asyncio +async def test_apipe_initial_coroutine_and_mixed_stage_types(): + async def initial() -> int: + return 2 + + async def length(value: str) -> int: + return len(value) + + assert_type(await apipe(initial()), int) + assert_type(await apipe(2), int) + value = await apipe(initial(), str, length, lambda x: x + 1) + assert_type(value, int) + assert value == 2 + + +@pytest.mark.asyncio +async def test_apipe_preserves_option_and_result_values(): + for value in (Some(1), NOTHING, Ok(1), Error("failure")): + assert await apipe(value) is value + assert await apipe(0, lambda _: value) is value + + async def result_value(_: int) -> Result[int, str]: + return Error("failure") + + assert await apipe(0, result_value) == Error("failure") + + +@pytest.mark.asyncio +async def test_apipe_long_pipeline(): + def increment(value: int) -> int: + return value + 1 + + stages: Any = [increment] * (sys.getrecursionlimit() + 100) + assert await apipe(0, *stages) == len(stages) + + +@pytest.mark.asyncio +async def test_apipe_is_deferred_and_sequential(): + events: list[str] = [] + + def first(value: int) -> int: + events.append("first") + return value + 1 + + async def second(value: int) -> int: + events.append("second started") + await asyncio.sleep(0) + events.append("second finished") + return value * 2 + + def third(value: int) -> int: + events.append("third") + return value + + operation = apipe(1, first, second, third) + assert events == [] + assert await operation == 4 + assert events == ["first", "second started", "second finished", "third"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("asynchronous", [False, True]) +async def test_apipe_propagates_exceptions(asynchronous: bool): + failure = ValueError("failure") + calls: list[int] = [] + + def fail(value: int) -> int: + raise failure + + async def async_fail(value: int) -> int: + raise failure + + with pytest.raises(ValueError) as caught: + await apipe(1, async_fail if asynchronous else fail, calls.append) + assert caught.value is failure + assert calls == [] + + +@pytest.mark.asyncio +async def test_apipe_propagates_cancellation(): + started = asyncio.Event() + calls: list[int] = [] + + async def wait(value: int) -> int: + started.set() + await asyncio.Event().wait() + return value + + task = asyncio.create_task(apipe(1, wait, calls.append)) + await started.wait() + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + assert calls == [] + + +@pytest.mark.asyncio +async def test_apipe_passes_futures_through_and_wrapper_awaits_them(): + future: asyncio.Future[int] = asyncio.get_running_loop().create_future() + future.set_result(42) + assert await apipe(future) is future + assert await apipe(0, lambda _: future) is future + + async def resolve(value: asyncio.Future[int]) -> int: + return await value + + assert await apipe(future, resolve) == 42 + + +@pytest.mark.asyncio +async def test_pipe_still_passes_coroutines_to_task_scheduler(): + async def increment(value: int) -> int: + return value + 1 + + task = pipe(1, increment, asyncio.create_task) + assert isinstance(task, asyncio.Task) + assert await task == 2 + + +@pytest.mark.asyncio +async def test_async_result_bind_preserves_error_and_skips_mapper(): + calls: list[int] = [] + + async def mapper(value: int) -> Result[str, str]: + calls.append(value) + return Error("mapper failed") + + bind = async_result.bind(mapper) + result_value = await bind(Error("initial failure")) + assert_type(result_value, Result[str, str]) + assert result_value == Error("initial failure") + assert calls == [] + assert await bind(Ok(1)) == Error("mapper failed") + assert calls == [1] + + +@pytest.mark.asyncio +async def test_async_result_bind_accepts_future_mapper(): + def mapper(value: int) -> asyncio.Future[Result[str, str]]: + future: asyncio.Future[Result[str, str]] = asyncio.get_running_loop().create_future() + future.set_result(Ok(str(value))) + return future + + assert await apipe(Ok(42), async_result.bind(mapper)) == Ok("42") diff --git a/typing_tests/negative.py b/typing_tests/negative.py index e577ff9d..ed948517 100644 --- a/typing_tests/negative.py +++ b/typing_tests/negative.py @@ -1,8 +1,10 @@ """Intentional caller errors; scripts/check_typing.py verifies each marked line.""" +from collections.abc import Awaitable, Callable from typing import Generic, Literal, TypeAlias, TypeVar, final -from expression import Error, MailboxProcessor, Nothing, Option, Result, Some, TaggedUnion, case, tag +from expression import Error, MailboxProcessor, Nothing, Option, Result, Some, TaggedUnion, apipe, case, tag +from expression.extra import async_result def unchecked(value: Option[int]) -> None: @@ -115,3 +117,26 @@ async def integer_mailbox_body(inbox: MailboxProcessor[int]) -> None: def invalid_mailbox_message() -> None: agent = MailboxProcessor.start(integer_mailbox_body) agent.post("wrong") # type-error + + +# Asynchronous composition must reject incompatible stages and error channels. + + +async def numeric_stage(value: int) -> int: + return value + 1 + + +def string_stage(value: str) -> str: + return value.upper() + + +async def wrong_async_stage() -> None: + await apipe(1, numeric_stage, string_stage) # type-error + + +async def integer_error(value: int) -> Result[str, int]: + return Error(42) + + +StringErrorBind = Callable[[Result[int, str]], Awaitable[Result[str, str]]] +wrong_async_bind: StringErrorBind = async_result.bind(integer_error) # type-error