Adds ContextFutureResult, refs #274

Author: sobolevn

docs/pages/context.rst

@@ -302,6 +302,55 @@ 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.
 
 
+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.
+
+We also added a lot of useful methods for this container,
+so you can work easily with it.
+
+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`
+  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_context`
+  allows to bind functions that return ``RequiresContext`` easily
+- :meth:`~RequiresContextFutureResult.bind_context_result`
+  allows to bind functions that return ``RequiresContextResult`` easily
+
+There are new ones:
+
+- :meth:`~RequiresContextFutureResult.bind_future`
+  allows to bind functions that return ``Future`` container
+- :meth:`~RequiresContextFutureResult.bind_future_result`
+  allows to bind functions that return ``FutureResult`` container
+- :meth:`~RequiresContextFutureResult.bind_async_future`
+  allows to bind async functions that return ``Future`` container
+- :meth:`~RequiresContextFutureResult.bind_async_future_result`
+  allows to bind async functions that return ``FutureResult`` container
+- :meth:`~RequiresContextFutureResult.bind_context_ioresult`
+  allows to bind functions that return ``RequiresContextIOResult``
+- :meth:`~RequiresContextFutureResult.bind_async`
+  allows to bind async functions
+  that return ``RequiresContextFutureResult`` container
+- :meth:`~RequiresContextFutureResult.bind_awaitable`
+  allows to bind async function that return raw values
+
+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.
+
+
 Aliases
 -------
 

docs/pages/railway.rst

@@ -169,7 +169,7 @@ when you try to ``.failure()`` a successful container.
 Note::
 
   Not all containers support these methods.
-  ``IO`` and ``RequiresContext`` cannot be unwrapped.
+  ``IO`` based containers and ``RequiresContext`` cannot be unwrapped.
 
 
 Further reading

returns/context/__init__.py

@@ -4,6 +4,9 @@
 from returns.context.requires_context import NoDeps as NoDeps
 from returns.context.requires_context import Reader as Reader
 from returns.context.requires_context import RequiresContext as RequiresContext
+from returns.context.requires_context_future_result import (
+    ContextFutureResult as ContextFutureResult,
+)
 from returns.context.requires_context_future_result import (
     ReaderFutureResult as ReaderFutureResult,
 )

returns/context/requires_context_future_result.py

@@ -1,3 +1,4 @@
+from abc import ABCMeta
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -16,6 +17,7 @@
 from returns.future import FutureResult
 from returns.io import IO, IOResult
 from returns.primitives.container import BaseContainer
+from returns.primitives.types import Immutable
 from returns.result import Result
 
 if TYPE_CHECKING:
@@ -674,6 +676,47 @@ def from_failure(
         )
 
 
+@final
+class ContextFutureResult(Immutable, Generic[_EnvType], metaclass=ABCMeta):
+    """
+    Helpers that can be used to work with ``ReaderFutureResult`` container.
+
+    Related to :class:`returns.context.requires_context.Context`
+    and :class:`returns.context.requires_context_result.ContextResult`,
+    refer there for the docs.
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def ask(cls) -> RequiresContextFutureResult[_EnvType, _EnvType, Any]:
+        """
+        Is used to get the current dependencies inside the call stack.
+
+        Similar to :meth:`returns.context.requires_context.Context.ask`,
+        but returns ``IOResult`` instead of a regular value.
+
+        Please, refer to the docs there to learn how to use it.
+
+        One important note that is worth duplicating here:
+        you might need to provide ``_EnvType`` explicitly,
+        so ``mypy`` will know about it statically.
+
+        .. code:: python
+
+          >>> import anyio
+          >>> from returns.context import ContextFutureResult
+          >>> from returns.io import IOSuccess
+
+          >>> assert anyio.run(
+          ...     ContextFutureResult[int].ask().map(str),
+          ...     1,
+          ... ) == IOSuccess('1')
+
+        """
+        return RequiresContextFutureResult(FutureResult.from_value)
+
+
 # Aliases:
 
 #: Alias for a popular case when ``Result`` has ``Exception`` as error type.

typesafety/test_context/test_requires_context_future_result/test_context_future_result.yml

@@ -0,0 +1,14 @@
+- case: context_result_future_ask1
+  disable_cache: true
+  main: |
+    from returns.context import ContextFutureResult
+
+    reveal_type(ContextFutureResult.ask())  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[<nothing>, <nothing>, Any]'
+
+
+- case: context_result_future_ask2
+  disable_cache: true
+  main: |
+    from returns.context import ContextFutureResult
+
+    reveal_type(ContextFutureResult[str].ask())  # N: Revealed type is 'returns.context.requires_context_future_result.RequiresContextFutureResult[builtins.str*, builtins.str*, Any]'