Adds bind_async_future and bind_async_future_result pointfree, closes #274

Author: sobolevn

docs/pages/pointfree.rst

@@ -105,7 +105,10 @@ We also have a long list of other ``bind_*`` functions, like:
 - ``bind_result`` to bind functions returning ``Result`` container
 - ``bind_ioresult`` to bind functions returning ``IOResult`` container
 - ``bind_future`` to bind functions returning ``Future`` container
+- ``bind_async_future`` to bind async functions returning ``Future`` container
 - ``bind_future_result`` to bind functions returning ``FutureResult`` container
+- ``bind_async_future_result`` to bind async functions
+  returning ``FutureResult`` container
 - ``bind_context`` to bind functions returning ``RequiresContext`` container
 - ``bind_context_result`` to bind functions
   returning ``RequiresContextResult`` container
@@ -241,8 +244,12 @@ API Reference
 
 .. autofunction:: returns.pointfree.bind_future
 
+.. autofunction:: returns.pointfree.bind_async_future
+
 .. autofunction:: returns.pointfree.bind_future_result
 
+.. autofunction:: returns.pointfree.bind_async_future_result
+
 .. autofunction:: returns.pointfree.bind_context
 
 .. autofunction:: returns.pointfree.bind_context_result

returns/_generated/pointfree/bind_async_future.py

@@ -0,0 +1,28 @@
+def _bind_async_future(function):
+    """
+    Compose a container and ``async`` function returning a `container`.
+
+    In other words, it modifies the function's
+    signature from: ``a -> Awaitable[Container[b]]``
+    to: ``Container[a] -> Container[b]``
+
+    This is how it should be used:
+
+    .. code:: python
+
+        >>> import anyio
+        >>> from returns.future import Future, FutureResult
+        >>> from returns.io import IOSuccess, IOFailure
+        >>> from returns.pointfree import bind_async_future
+
+        >>> async def coroutine(x: int) -> Future[str]:
+        ...    return Future.from_value(str(x + 1))
+
+        >>> bound = bind_async_future(coroutine)(FutureResult.from_value(1))
+        >>> assert anyio.run(bound.awaitable) == IOSuccess('2')
+
+        >>> bound = bind_async_future(coroutine)(FutureResult.from_failure(1))
+        >>> assert anyio.run(bound.awaitable) == IOFailure(1)
+
+    """
+    return lambda container: container.bind_async_future(function)

returns/_generated/pointfree/bind_async_future.pyi

@@ -0,0 +1,44 @@
+from typing import Awaitable, Callable, TypeVar, overload
+
+from typing_extensions import Protocol
+
+from returns.context import RequiresContextFutureResult
+from returns.future import Future, FutureResult
+
+_ValueType = TypeVar('_ValueType', contravariant=True)
+_ErrorType = TypeVar('_ErrorType')
+_NewValueType = TypeVar('_NewValueType', covariant=True)
+_EnvType = TypeVar('_EnvType')
+
+
+class _BindAsyncFuture(Protocol[_ValueType, _NewValueType]):
+    """
+    Helper class to represent type overloads for ret_type based on a value type.
+
+    Contains all containers we have.
+
+    It does not exist in runtime.
+    It is also completely removed from typing with the help of the mypy plugin.
+    """
+
+    @overload
+    def __call__(
+        self,
+        container: FutureResult[_ValueType, _ErrorType],
+    ) -> FutureResult[_NewValueType, _ErrorType]:
+        ...
+
+    @overload
+    def __call__(
+        self,
+        container: RequiresContextFutureResult[
+            _EnvType, _ValueType, _ErrorType,
+        ],
+    ) -> RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]:
+        ...
+
+
+def _bind_async_future(
+    function: Callable[[_ValueType], Awaitable[Future[_NewValueType]]],
+) -> _BindAsyncFuture[_ValueType, _NewValueType]:
+    ...

returns/_generated/pointfree/bind_async_future_result.py

@@ -0,0 +1,33 @@
+def _bind_async_future_result(function):
+    """
+    Compose a container and ``async`` function returning a ``FutureResult``.
+
+    In other words, it modifies the function's
+    signature from: ``a -> Awaitable[FutureResult[b, c]]``
+    to: ``Container[a, c] -> Container[b, c]``
+
+    This is how it should be used:
+
+    .. code:: python
+
+        >>> import anyio
+        >>> from returns.future import FutureResult
+        >>> from returns.context import ReaderFutureResult
+        >>> from returns.io import IOSuccess, IOFailure
+        >>> from returns.pointfree import bind_async_future_result
+
+        >>> async def coroutine(x: int) -> FutureResult[str, int]:
+        ...    return FutureResult.from_value(str(x + 1))
+
+        >>> bound = bind_async_future_result(coroutine)(
+        ...     ReaderFutureResult.from_value(1),
+        ... )
+        >>> assert anyio.run(bound, ReaderFutureResult.empty) == IOSuccess('2')
+
+        >>> bound = bind_async_future_result(coroutine)(
+        ...     ReaderFutureResult.from_failure(1),
+        ... )
+        >>> assert anyio.run(bound, ReaderFutureResult.empty) == IOFailure(1)
+
+    """
+    return lambda container: container.bind_async_future_result(function)

returns/_generated/pointfree/bind_async_future_result.pyi

@@ -0,0 +1,39 @@
+from typing import Awaitable, Callable, TypeVar, overload
+
+from typing_extensions import Protocol
+
+from returns.context import RequiresContextFutureResult
+from returns.future import FutureResult
+
+_ValueType = TypeVar('_ValueType', contravariant=True)
+_ErrorType = TypeVar('_ErrorType')
+_NewValueType = TypeVar('_NewValueType', covariant=True)
+_EnvType = TypeVar('_EnvType')
+
+
+class _BindAsyncFutureResult(Protocol[_ValueType, _NewValueType, _ErrorType]):
+    """
+    Helper class to represent type overloads for ret_type based on a value type.
+
+    Contains all containers we have.
+
+    It does not exist in runtime.
+    It is also completely removed from typing with the help of the mypy plugin.
+    """
+
+    def __call__(
+        self,
+        container: RequiresContextFutureResult[
+            _EnvType, _ValueType, _ErrorType,
+        ],
+    ) -> RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]:
+        ...
+
+
+def _bind_async_future_result(
+    function: Callable[
+        [_ValueType],
+        Awaitable[FutureResult[_NewValueType, _ErrorType]],
+    ],
+) -> _BindAsyncFutureResult[_ValueType, _NewValueType, _ErrorType]:
+    ...

returns/contrib/mypy/returns_plugin.py

@@ -53,7 +53,12 @@
     'returns._generated.pointfree.bind_io._bind_io',
     'returns._generated.pointfree.bind_ioresult._bind_ioresult',
     'returns._generated.pointfree.bind_future._bind_future',
+    'returns._generated.pointfree.bind_async_future._bind_async_future',
     'returns._generated.pointfree.bind_future_result._bind_future_result',
+    (
+        'returns._generated.pointfree.bind_async_future_result.' +
+        '_bind_async_future_result'
+    ),
     'returns._generated.pointfree.bind_context._bind_context',
     'returns._generated.pointfree.bind_context_result._bind_context_result',
     'returns._generated.pointfree.bind_context_ioresult._bind_context_ioresult',

returns/pointfree.py

@@ -2,6 +2,12 @@
 from returns._generated.pointfree.apply import _apply as apply
 from returns._generated.pointfree.bind import _bind as bind
 from returns._generated.pointfree.bind_async import _bind_async as bind_async
+from returns._generated.pointfree.bind_async_future import (
+    _bind_async_future as bind_async_future,
+)
+from returns._generated.pointfree.bind_async_future_result import (
+    _bind_async_future_result as bind_async_future_result,
+)
 from returns._generated.pointfree.bind_awaitable import (
     _bind_awaitable as bind_awaitable,
 )

typesafety/test_pointfree/test_bind_async_future.yml

@@ -0,0 +1,43 @@
+- case: bind_async_future_and_flow
+  disable_cache: true
+  main: |
+    from returns.functions import identity
+    from returns.pointfree import bind_async_future, bind
+    from returns.future import Future, FutureResult
+    from returns.pipeline import flow
+
+    async def test(arg: int) -> Future[float]:
+        ...
+
+    def second(arg: float) -> FutureResult[bool, str]:
+        ...
+
+    r: FutureResult[int, str]
+    reveal_type(flow(r, bind_async_future(test), bind(second), identity))  # N: Revealed type is 'returns.future.FutureResult*[builtins.bool*, builtins.str*]'
+
+
+- case: bind_async_future_futureresult
+  disable_cache: true
+  main: |
+    from returns.pointfree import bind_async_future
+    from returns.future import Future, FutureResult
+
+    async def test(arg: float) -> Future[int]:
+        ...
+
+    x: FutureResult[float, str]
+    reveal_type(bind_async_future(test)(x))  # N: Revealed type is 'returns.future.FutureResult[builtins.int, builtins.str*]'
+
+
+- case: bind_async_future_requires_context_future_result
+  disable_cache: true
+  main: |
+    from returns.pointfree import bind_async_future
+    from returns.future import Future
+    from returns.context import ReaderFutureResult
+
+    async def test(arg: float) -> Future[int]:
+        ...
+
+    x: ReaderFutureResult[bool, float, Exception]
+    reveal_type(bind_async_future(test)(x))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool*, builtins.int, builtins.Exception*]'

typesafety/test_pointfree/test_bind_async_future_result.yml

@@ -0,0 +1,28 @@
+- case: bind_async_future_and_flow
+  disable_cache: true
+  main: |
+    from returns.functions import identity
+    from returns.pointfree import bind_async_future_result
+    from returns.future import FutureResult
+    from returns.context import ReaderFutureResult
+    from returns.pipeline import flow
+
+    async def test(arg: int) -> FutureResult[float, str]:
+        ...
+
+    r: ReaderFutureResult[object, int, str]
+    reveal_type(flow(r, bind_async_future_result(test), identity))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult*[builtins.object*, builtins.float, builtins.str]'
+
+
+- case: bind_async_future_result_requires_context_future_result
+  disable_cache: true
+  main: |
+    from returns.pointfree import bind_async_future_result
+    from returns.future import FutureResult
+    from returns.context import ReaderFutureResult
+
+    async def test(arg: float) -> FutureResult[int, Exception]:
+        ...
+
+    x: ReaderFutureResult[bool, float, Exception]
+    reveal_type(bind_async_future_result(test)(x))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool*, builtins.int, builtins.Exception]'