Adds .bind_future_result and .bind_future to ReaderFutureResult, refs #274

Author: sobolevn

docs/pages/context.rst

@@ -302,12 +302,78 @@ Use it when you work with impure context-related functions that might fail.
 This is basically **the main type** that is going to be used in most apps.
 
 
+.. _requires_context_future_result:
+
 RequiresContextFutureResult container
 -------------------------------------
 
 This container is a combintaion of ``RequiresContext[env, FutureResult[a, b]]``.
 Which means that it is a wrapper around impure async function that might fail.
 
+Here's how it should be used:
+
+.. code:: python
+
+  from typing import Sequence
+
+  import anyio  # you wound need to `pip install anyio`
+  import httpx  # you wound need to `pip install httpx`
+  from typing_extensions import Final, TypedDict
+
+  from returns.context import ContextFutureResult, RequiresContextFutureResultE
+  from returns.functions import tap
+  from returns.future import FutureResultE, future_safe
+  from returns.pipeline import managed
+
+  _URL: Final = 'https://jsonplaceholder.typicode.com/posts/{0}'
+  _Post = TypedDict('_Post', {
+      'id': int,
+      'userId': int,
+      'title': str,
+      'body': str,
+  })
+  _TitleOnly = TypedDict('_TitleOnly', {'title': str})
+
+  def _close(client: httpx.AsyncClient, _) -> FutureResultE[None]:
+      return future_safe(client.aclose)()
+
+  def _fetch_post(
+      post_id: int,
+  ) -> RequiresContextFutureResultE[httpx.AsyncClient, _Post]:
+      return ContextFutureResult[httpx.AsyncClient].ask().bind_future_result(
+          lambda client: future_safe(client.get)(_URL.format(post_id)),
+      ).map(
+          lambda response: tap(httpx.Response.raise_for_status)(response),
+      ).map(
+          lambda response: response.json(),
+      )
+
+  def show_titles(
+      number_of_posts: int,
+  ) -> RequiresContextFutureResultE[httpx.AsyncClient, Sequence[_TitleOnly]]:
+      return RequiresContextFutureResultE.from_iterable([
+          # Notice how easily we compose async and sync functions:
+          _fetch_post(post_id).map(lambda post: post['title'])
+          # TODO: try `for post_id in {2, 1, 0}:` to see how errors work
+          for post_id in range(1, number_of_posts + 1)
+      ])
+
+  if __name__ == '__main__':
+      # Let's fetch 3 titles of posts asynchronously:
+      managed_httpx = managed(show_titles(3), _close)
+      future_result = managed_httpx(
+          FutureResultE.from_value(httpx.AsyncClient(timeout=5)),
+      )
+      print(anyio.run(future_result.awaitable))
+      # <IOResult: <Success: (
+      #    'sunt aut facere repellat provident occaecati ...',
+      #    'qui est esse',
+      #    'ea molestias quasi exercitationem repellat qui ipsa sit aut',
+      # )>>
+
+This example illustrates the whole point of our actions: writting
+sync code that executes asynchronously without any magic at all!
+
 We also added a lot of useful methods for this container,
 so you can work easily with it.
 
@@ -324,6 +390,8 @@ These methods are identical with ``RequiresContextIOResult``:
   allows to bind functions that return ``IO`` with just one call
 - :meth:`~RequiresContextFutureResult.bind_ioresult`
   allows to bind functions that return ``IOResult`` with just one call
+- :meth:`~RequiresContextFutureResult.bind_future_result`
+  allows to bind functions that return ``FutureResult`` with just one call
 - :meth:`~RequiresContextFutureResult.bind_context`
   allows to bind functions that return ``RequiresContext`` easily
 - :meth:`~RequiresContextFutureResult.bind_context_result`

docs/pages/future.rst

@@ -85,8 +85,8 @@ Let's see how it can be used in a real program:
 
   from typing import Sequence
 
-  import anyio
-  import httpx
+  import anyio  # you would need to `pip install anyio`
+  import httpx  # you would need to `pip install httpx`
   from typing_extensions import Final, TypedDict
   from returns.future import FutureResultE, future_safe
 
@@ -134,6 +134,11 @@ What is different?
    In this example any error will cancel the whole pipeline
 3. We now have ``.map`` method to easily compose sync and async functions
 
+You can see the next example
+with :ref:`RequiresContextFutureResult <requires_context_future_result>`
+and without a single ``async/await``.
+That example illustrates the whole point of our actions: writting
+sync code that executes asynchronously without any magic at all.
 
 Aliases
 -------

returns/_generated/pointfree/bind_future.py

@@ -26,7 +26,6 @@ def _bind_future(function):
         ...     container = FutureResult.from_failure(1)
         ...     return await bind_future(example)(container)
 
-
         >>> assert anyio.run(success) == IOSuccess(0.5)
         >>> assert anyio.run(failure) == IOFailure(1)
 

returns/_generated/pointfree/bind_future.pyi

@@ -1,12 +1,14 @@
-from typing import Callable, TypeVar
+from typing import Callable, TypeVar, overload
 
 from typing_extensions import Protocol
 
 from returns.future import Future, FutureResult
+from returns.context import RequiresContextFutureResult
 
 _ValueType = TypeVar('_ValueType', contravariant=True)
 _ErrorType = TypeVar('_ErrorType')
 _NewValueType = TypeVar('_NewValueType', covariant=True)
+_EnvType = TypeVar('_EnvType')
 
 
 class _BindFuture(Protocol[_ValueType, _NewValueType]):
@@ -19,12 +21,22 @@ class _BindFuture(Protocol[_ValueType, _NewValueType]):
     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_future(
     function: Callable[[_ValueType], Future[_NewValueType]],

returns/_generated/pointfree/bind_future_result.py

@@ -0,0 +1,31 @@
+def _bind_future_result(function):
+    """
+    Lifts ``FutureResult`` function to be wrapped in other container.
+
+    In other words, it modifies the function's
+    signature from: ``a -> 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 FutureResultE
+        >>> from returns.context import ReaderFutureResultE
+        >>> from returns.io import IOSuccess, IOFailure
+        >>> from returns.pointfree import bind_future_result
+
+        >>> def example(argument: int) -> FutureResultE[float]:
+        ...     return FutureResultE.from_value(argument / 2)
+
+        >>> assert anyio.run(bind_future_result(example)(
+        ...     ReaderFutureResultE.from_value(1),
+        ... ), ReaderFutureResultE.empty) == IOSuccess(0.5)
+
+        >>> assert anyio.run(bind_future_result(example)(
+        ...     ReaderFutureResultE.from_failure(':('),
+        ... ), ReaderFutureResultE.empty) == IOFailure(':(')
+
+    """
+    return lambda container: container.bind_future_result(function)

returns/_generated/pointfree/bind_future_result.pyi

@@ -0,0 +1,36 @@
+from typing import Callable, TypeVar
+
+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 _BindFutureResult(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_future_result(
+    function: Callable[[_ValueType], FutureResult[_NewValueType, _ErrorType]],
+) -> _BindFutureResult[_ValueType, _NewValueType, _ErrorType]:
+    ...

returns/context/requires_context_future_result.py

@@ -449,6 +449,79 @@ def bind_ioresult(
             lambda deps: self(deps).bind_ioresult(function),
         )
 
+    def bind_future(
+        self,
+        function: Callable[[_ValueType], Future[_NewValueType]],
+    ) -> 'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]':
+        """
+        Binds ``Future`` returning function to the current container.
+
+        .. code:: python
+
+          >>> import anyio
+          >>> from returns.context import RequiresContextFutureResult
+          >>> from returns.future import Future
+          >>> from returns.io import IOSuccess, IOFailure
+
+          >>> def function(num: int) -> Future[int]:
+          ...     return Future.from_value(num + 1)
+
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_value(1).bind_future(
+          ...         function,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOSuccess(2)
+
+          >>> failed = RequiresContextFutureResult.from_failure(':(')
+          >>> assert anyio.run(
+          ...     failed.bind_future_result(function),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOFailure(':(')
+
+        """
+        return RequiresContextFutureResult(
+            lambda deps: self(deps).bind_future(function),
+        )
+
+    def bind_future_result(
+        self,
+        function: Callable[
+            [_ValueType],
+            FutureResult[_NewValueType, _ErrorType],
+        ],
+    ) -> 'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]':
+        """
+        Binds ``FutureResult`` returning function to the current container.
+
+        .. code:: python
+
+          >>> import anyio
+          >>> from returns.context import RequiresContextFutureResult
+          >>> from returns.future import FutureResult
+          >>> from returns.io import IOSuccess, IOFailure
+
+          >>> def function(num: int) -> FutureResult[int, str]:
+          ...     return FutureResult.from_value(num + 1)
+
+          >>> assert anyio.run(
+          ...     RequiresContextFutureResult.from_value(1).bind_future_result(
+          ...         function,
+          ...     ),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOSuccess(2)
+
+          >>> failed = RequiresContextFutureResult.from_failure(':(')
+          >>> assert anyio.run(
+          ...     failed.bind_future_result(function),
+          ...     RequiresContextFutureResult.empty,
+          ... ) == IOFailure(':(')
+
+        """
+        return RequiresContextFutureResult(
+            lambda deps: self(deps).bind(function),
+        )
+
     def fix(
         self, function: Callable[[_ErrorType], _NewValueType],
     ) -> 'RequiresContextFutureResult[_EnvType, _NewValueType, _ErrorType]':
@@ -781,14 +854,14 @@ def from_failed_future(
           >>> import anyio
           >>> from returns.context import RequiresContextFutureResult
           >>> from returns.future import Future
-          >>> from returns.io import IOSuccess
+          >>> from returns.io import IOFailure
 
           >>> assert anyio.run(
           ...    RequiresContextFutureResult.from_failed_future(
           ...        Future.from_value(1),
           ...    ),
           ...    RequiresContextFutureResult.empty,
-          ... ) == IOSuccess(1)
+          ... ) == IOFailure(1)
 
         """
         return RequiresContextFutureResult(

returns/contrib/mypy/returns_plugin.py

@@ -53,6 +53,7 @@
     '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_future_result._bind_future_result',
     'returns._generated.pointfree.bind_context._bind_context',
     'returns._generated.pointfree.bind_context_result._bind_context_result',
     'returns._generated.pointfree.bind_awaitable._bind_awaitable',

returns/pointfree.py

@@ -12,6 +12,9 @@
     _bind_context_result as bind_context_result,
 )
 from returns._generated.pointfree.bind_future import _bind_future as bind_future
+from returns._generated.pointfree.bind_future_result import (
+    _bind_future_result as bind_future_result,
+)
 from returns._generated.pointfree.bind_io import _bind_io as bind_io
 from returns._generated.pointfree.bind_ioresult import (
     _bind_ioresult as bind_ioresult,

typesafety/test_context/test_requires_context_future_result/test_requires_context_future_result.yml

@@ -75,6 +75,20 @@
     reveal_type(x.bind_io(test))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.str, builtins.bool*, builtins.float]'
 
 
+- case: requires_context_futureresult_bind_future_result
+  disable_cache: true
+  main: |
+    from returns.context import RequiresContextFutureResult
+    from returns.future import FutureResult
+
+    x: RequiresContextFutureResult[str, int, float]
+
+    def test(param: int) -> FutureResult[bool, float]:
+        ...
+
+    reveal_type(x.bind_future_result(test))  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.str, builtins.bool*, builtins.float]'
+
+
 - case: requires_context_future_result_bind_context
   disable_cache: true
   main: |