Adds .bind_async and .bind_awaitable, refs #274

Author: sobolevn

docs/pages/context.rst

@@ -260,9 +260,6 @@ so you can work easily with it:
 
 .. currentmodule:: returns.context.requires_context_result
 
-- :meth:`~RequiresContextResult.from_typecast`
-  turns accidental ``RequiresContext[env, Result[a, b]]`` into
-  full-featured ``RequiresContextResult[env, a, b]``
 - :meth:`~RequiresContextResult.bind_result`
   allows to bind functions that return ``Result`` with just one call
 - :meth:`~RequiresContextResult.bind_context`
@@ -283,9 +280,6 @@ so you can work easily with it:
 
 .. currentmodule:: returns.context.requires_context_ioresult
 
-- :meth:`~RequiresContextIOResult.from_typecast`
-  turns accidental ``RequiresContext[env, IOResult[a, b]]`` into
-  full-featured ``RequiresContextIOResult[env, a, b]``
 - :meth:`~RequiresContextIOResult.bind_result`
   allows to bind functions that return ``Result`` with just one call
 - :meth:`~RequiresContextIOResult.bind_io`
@@ -381,9 +375,6 @@ These methods are identical with ``RequiresContextIOResult``:
 
 .. currentmodule:: returns.context.requires_context_future_result
 
-- :meth:`~RequiresContextFutureResult.from_typecast`
-  turns accidental ``RequiresContext[env, IOResult[a, b]]`` into
-  full-featured ``RequiresContextFutureResult[env, a, b]``
 - :meth:`~RequiresContextFutureResult.bind_result`
   allows to bind functions that return ``Result`` with just one call
 - :meth:`~RequiresContextFutureResult.bind_io`

returns/_generated/futures/_future_result.py

@@ -41,7 +41,7 @@ async def async_bind(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return (await function(container.unwrap()))._inner_value
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_bind_awaitable(
@@ -52,7 +52,7 @@ async def async_bind_awaitable(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return Result.from_value(await function(container.unwrap()))
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_bind_async(
@@ -66,7 +66,7 @@ async def async_bind_async(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return await (await function(container.unwrap()))._inner_value
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_bind_result(
@@ -85,7 +85,7 @@ async def async_bind_ioresult(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return function(container.unwrap())._inner_value
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_bind_io(
@@ -96,7 +96,7 @@ async def async_bind_io(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return Success(function(container.unwrap())._inner_value)
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_bind_future(
@@ -107,7 +107,7 @@ async def async_bind_future(
     container = await inner_value
     if isinstance(container, Result.success_type):
         return await async_from_success(function(container.unwrap()))
-    return container  # type: ignore
+    return container  # type: ignore[return-value]
 
 
 async def async_fix(

returns/_generated/futures/_reader_future_result.py

@@ -0,0 +1,28 @@
+from typing import TYPE_CHECKING, Awaitable, Callable, TypeVar
+
+from returns.result import Result
+
+if TYPE_CHECKING:
+    from returns.context import RequiresContextFutureResult  # noqa: F401
+
+_ValueType = TypeVar('_ValueType', covariant=True)
+_NewValueType = TypeVar('_NewValueType')
+_ErrorType = TypeVar('_ErrorType', covariant=True)
+_EnvType = TypeVar('_EnvType')
+
+
+async def async_bind_async(
+    function: Callable[
+        [_ValueType],
+        Awaitable[
+            'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]',
+        ],
+    ],
+    container: 'RequiresContextFutureResult[_EnvType, _ValueType, _ErrorType]',
+    deps: _EnvType,
+) -> Result[_NewValueType, _ErrorType]:
+    """Async binds a coroutine with container over a value."""
+    inner_value = await container(deps)._inner_value
+    if isinstance(inner_value, Result.success_type):
+        return await (await function(inner_value.unwrap()))(deps)._inner_value
+    return inner_value  # type: ignore[return-value]

returns/_generated/pointfree/bind_async.pyi

@@ -1,10 +1,12 @@
 from typing import Awaitable, Callable, TypeVar, overload
 
+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')
 
 
 @overload
@@ -25,3 +27,18 @@ def _bind_async(
     FutureResult[_NewValueType, _ErrorType],
 ]:
     ...
+
+
+@overload
+def _bind_async(
+    function: Callable[
+        [_ValueType],
+        Awaitable[RequiresContextFutureResult[
+            _EnvType, _NewValueType, _ErrorType,
+        ]],
+    ],
+) -> Callable[
+    [RequiresContextFutureResult[_EnvType, _ValueType, _ErrorType]],
+    RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType],
+]:
+    ...

returns/_generated/pointfree/bind_awaitable.pyi

@@ -2,11 +2,13 @@ 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 _BindAwaitable(Protocol[_ValueType, _NewValueType]):
@@ -33,6 +35,15 @@ class _BindAwaitable(Protocol[_ValueType, _NewValueType]):
     ) -> FutureResult[_NewValueType, _ErrorType]:
         ...
 
+    @overload
+    def __call__(
+        self,
+        container: RequiresContextFutureResult[
+            _EnvType, _ValueType, _ErrorType,
+        ],
+    ) -> RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]:
+        ...
+
 
 def _bind_awaitable(
     function: Callable[[_ValueType], Awaitable[_NewValueType]],

returns/context/requires_context_future_result.py

@@ -14,7 +14,7 @@
 
 from typing_extensions import final
 
-from returns._generated.futures import _future_result
+from returns._generated.futures import _future_result, _reader_future_result
 from returns._generated.iterable import iterable
 from returns.context import NoDeps
 from returns.future import Future, FutureResult
@@ -264,6 +264,89 @@ def bind(
             ),
         )
 
+    def bind_async(
+        self,
+        function: Callable[
+            [_ValueType],
+            Awaitable[
+                'RequiresContextFutureResult'
+                '[_EnvType, _NewValueType, _ErrorType]'
+            ],
+        ],
+    ) -> 'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]':
+        """
+        Composes this container with a async function returning the same type.
+
+        .. code:: python
+
+          >>> import anyio
+          >>> from returns.context import RequiresContextFutureResult
+          >>> from returns.io import IOSuccess, IOFailure
+
+          >>> async def function(
+          ...     number: int,
+          ... ) -> RequiresContextFutureResult[int, str, int]:
+          ...     return RequiresContextFutureResult.from_value(number + 1)
+
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_value(1).bind_async(
+          ...        function,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOSuccess(2)
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_failure(1).bind_async(
+          ...        function,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOFailure(1)
+
+        """
+        return RequiresContextFutureResult(
+            lambda deps: FutureResult(_reader_future_result.async_bind_async(
+                function, self, deps,
+            )),
+        )
+
+    def bind_awaitable(
+        self,
+        function: Callable[[_ValueType], 'Awaitable[_NewValueType]'],
+    ) -> 'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]':
+        """
+        Allows to compose a container and a regular ``async`` function.
+
+        This function should return plain, non-container value.
+        See :meth:`~RequiresContextFutureResult.bind_async`
+        to bind ``async`` function that returns a container.
+
+        .. code:: python
+
+          >>> import anyio
+          >>> from returns.context import RequiresContextFutureResult
+          >>> from returns.io import IOSuccess, IOFailure
+
+          >>> async def coroutine(x: int) -> int:
+          ...    return x + 1
+
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_value(1).bind_awaitable(
+          ...         coroutine,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOSuccess(2)
+
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_failure(1).bind_awaitable(
+          ...         coroutine,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOFailure(1)
+
+        """
+        return RequiresContextFutureResult(
+            lambda deps: self(deps).bind_awaitable(function),
+        )
+
     def bind_result(
         self,
         function: Callable[[_ValueType], 'Result[_NewValueType, _ErrorType]'],

typesafety/test_context/test_requires_context_future_result/test_requires_context_future_result.yml

@@ -33,6 +33,32 @@
     reveal_type(x.bind(test))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.str, builtins.bool*, builtins.float]'
 
 
+- case: requires_context_future_result_bind_awaitable
+  disable_cache: true
+  main: |
+    from returns.context import RequiresContextFutureResult
+
+    async def bind_awaitable(arg: int) -> float:
+        ...
+
+    first: RequiresContextFutureResult[bool, int, str]
+
+    reveal_type(first.bind_awaitable(bind_awaitable))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool, builtins.float*, builtins.str]'
+
+
+- case: requires_context_future_result_bind_async
+  disable_cache: true
+  main: |
+    from returns.context import RequiresContextFutureResult
+
+    async def bind_async(arg: int) -> RequiresContextFutureResult[bool, float, str]:
+        ...
+
+    first: RequiresContextFutureResult[bool, int, str]
+
+    reveal_type(first.bind_async(bind_async))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool, builtins.float*, builtins.str]'
+
+
 - case: requires_context_future_result_bind_result
   disable_cache: true
   main: |

typesafety/test_pointfree/test_bind_async.yml

@@ -22,3 +22,17 @@
 
     x: FutureResult[float, str]
     reveal_type(bind_async(test)(x))  # N: Revealed type is 'returns.future.FutureResult[builtins.int*, builtins.str*]'
+
+
+- case: bind_async_requires_context_future_result
+  disable_cache: true
+  main: |
+    from returns.pointfree import bind_async
+    from returns.context import RequiresContextFutureResult
+
+    async def test(arg: int) -> RequiresContextFutureResult[bool, float, str]:
+        ...
+
+    first: RequiresContextFutureResult[bool, int, str]
+
+    reveal_type(bind_async(test)(first))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool*, builtins.float*, builtins.str*]'

typesafety/test_pointfree/test_bind_awaitable.yml

@@ -58,3 +58,17 @@
 
     x: FutureResult[float, str]
     reveal_type(bind_awaitable(test)(x))  # N: Revealed type is 'returns.future.FutureResult[builtins.int, builtins.str*]'
+
+
+- case: bind_awaitable_requires_context_future_result
+  disable_cache: true
+  main: |
+    from returns.pointfree import bind_awaitable
+    from returns.context import RequiresContextFutureResult
+
+    async def test(arg: int) -> float:
+        ...
+
+    first: RequiresContextFutureResult[bool, int, str]
+
+    reveal_type(bind_awaitable(test)(first))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.bool*, builtins.float, builtins.str*]'