Refs #243

Author: sobolevn

CHANGELOG.md

@@ -36,6 +36,12 @@ See [0Ver](https://0ver.org/).
 - Adds `IOResult` support for `fold`
 - Adds `IOResult` support for `is_successful`
 
+- Adds `RequiresContextIOResult` container
+- Adds `RequiresContextIOResultE` alias
+  for `RequiresContextIOResult[..., ..., Exception]`
+- Adds `RequiresContextIOResult` support for `bind` and `rescue`
+- Adds `RequiresContextIOResult` support for `flatten`
+
 - Adds `Result.lift`, `Maybe.lift`, `RequiresContext.lift`,
   and `RequiresContextResult.lift` functions in addition to `IO.lift`
 - Adds `Immutable` primitive type

docs/pages/container.rst

@@ -10,10 +10,12 @@ while maintaining the execution context.
 List of supported containers:
 
 - :class:`Maybe <returns.maybe.Maybe>` to handle ``None`` cases
-- :class:`RequiresContext <returns.context.requires_context.RequiresContext>`
-  to pass context to your functions
-- :class:`IO <returns.io.IO>` to mark explicit ``IO`` actions
 - :class:`Result <returns.result.Result>` to handle possible exceptions
+- :class:`IO <returns.io.IO>` to mark explicit ``IO`` actions
+- :class:`RequiresContext <returns.context.requires_context.RequiresContext>`
+  to pass context to your functions (DI and similar)
+
+There are also some combintations like
 
 We will show you container's simple API of one attribute
 and several simple methods.
@@ -178,12 +180,20 @@ Needs transformation
   use :func:`result_to_maybe <returns.converters.result_to_maybe>`
   and then :func:`flatten <returns.converters.flatten>`
 - ``RequiresContext[env, Result[A, B]]`` 🤔,
-  use :meth:`returns.context.requires_context_result.from_typecast`
+  use
+  :meth:`returns.context.requires_context_result.RequiresContextResult.from_typecast`
   and ``RequiresResultContext``
 - ``RequiresContext[env, RequiresContext[env, A]]`` 🤔,
   use :func:`flatten <returns.converters.flatten>`
 - ``RequiresContextResult[env, RequiresContextResult[env, A, B], B]`` 🤔,
   use :func:`flatten <returns.converters.flatten>`
+- ``RequiresContext[env, IOResult[A, B]]`` 🤔,
+  use
+  :meth:`returns.context.requires_context_io_result.RequiresContextIOResult.from_typecast`
+  and ``RequiresResultContext``
+  - ``RequiresContextIOResult[env, RequiresContextIOResult[env, A, B], B]``
+  🤔,
+  use :func:`flatten <returns.converters.flatten>`
 
 Nope
 ~~~~
@@ -194,6 +204,7 @@ Nope
 - ``Result[A, Result[B, C]]`` 🚫
 - ``Maybe[IO[A]]`` 🚫
 - ``RequiresContext[IO[A], B]`` 🚫
+- ``IO[RequiresContext[A, B]`` 🚫
 
 You can use :ref:`converters` to convert ``Maybe`` and ``Result`` containers.
 You can also use :func:`flatten <returns.converters.flatten>`

docs/pages/context.rst

@@ -321,6 +321,15 @@ But, think twice: why would you need to do it?
 These classes represent computations that rely on context.
 Maybe, you should not do creat their units?
 
+``RequiresContextIOResult`` requires you to use one of the following methods:
+
+- ``from_success`` when you want to mark some raw value as a ``Success``
+- ``from_failure`` when you want to mark some raw value as a ``Failure``
+- ``from_result`` when you already have ``Result`` container
+- ``from_ioresult`` when you already have ``IOResult`` container
+- ``from_successful_context`` when you have successful ``RequiresContext``
+- ``from_failed_context`` when you have failed ``RequiresContext``
+
 How can I access dependencies inside the context?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -373,3 +382,11 @@ RequiresContextResult
 
 .. automodule:: returns.context.requires_context_result
    :members:
+
+RequiresContextIOResult
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclasstree:: returns.context.requires_context_io_result
+
+.. automodule:: returns.context.requires_context_io_result
+   :members:

returns/_generated/flatten.pyi

@@ -2,7 +2,11 @@
 
 from typing import TypeVar, overload
 
-from returns.context import RequiresContext, RequiresContextResult
+from returns.context import (
+    RequiresContext,
+    RequiresContextIOResult,
+    RequiresContextResult,
+)
 from returns.io import IO, IOResult
 from returns.maybe import Maybe
 from returns.result import Result
@@ -54,3 +58,14 @@ def _flatten(
     ],
 ) -> RequiresContextResult[_EnvType, _ValueType, _ErrorType]:
     ...
+
+
+@overload
+def _flatten(
+    container: RequiresContextIOResult[
+        _EnvType,
+        RequiresContextIOResult[_EnvType, _ValueType, _ErrorType],
+        _ErrorType,
+    ],
+) -> RequiresContextIOResult[_EnvType, _ValueType, _ErrorType]:
+    ...

returns/_generated/pointfree/bind.pyi

@@ -2,7 +2,11 @@
 
 from typing import Callable, TypeVar, overload
 
-from returns.context import RequiresContext, RequiresContextResult
+from returns.context import (
+    RequiresContext,
+    RequiresContextIOResult,
+    RequiresContextResult,
+)
 from returns.io import IO, IOResult
 from returns.maybe import Maybe
 from returns.result import Result
@@ -52,6 +56,19 @@ def _bind(
     ...
 
 
+@overload
+def _bind(
+    function: Callable[
+        [_ValueType],
+        RequiresContextIOResult[_EnvType, _NewValueType, _ErrorType],
+    ],
+) -> Callable[
+    [RequiresContextIOResult[_EnvType, _ValueType, _ErrorType]],
+    RequiresContextIOResult[_EnvType, _NewValueType, _ErrorType],
+]:
+    ...
+
+
 @overload
 def _bind(
     function: Callable[[_ValueType], Result[_NewValueType, _ErrorType]],

returns/_generated/pointfree/rescue.pyi

@@ -2,7 +2,7 @@
 
 from typing import Callable, TypeVar, overload
 
-from returns.context import RequiresContextResult
+from returns.context import RequiresContextIOResult, RequiresContextResult
 from returns.io import IOResult
 from returns.result import Result
 
@@ -47,3 +47,16 @@ def _rescue(
     RequiresContextResult[_EnvType, _ValueType, _NewErrorType],
 ]:
     ...
+
+
+@overload
+def _rescue(
+    function: Callable[
+        [_ErrorType],
+        RequiresContextIOResult[_EnvType, _ValueType, _NewErrorType],
+    ],
+) -> Callable[
+    [RequiresContextIOResult[_EnvType, _ValueType, _ErrorType]],
+    RequiresContextIOResult[_EnvType, _ValueType, _NewErrorType],
+]:
+    ...

returns/context/__init__.py

@@ -15,3 +15,8 @@
     RequiresContextResult as RequiresContextResult,
     RequiresContextResultE as RequiresContextResultE,
 )
+from returns.context.requires_context_io_result import (  # noqa: F401
+    ContextIOResult as ContextIOResult,
+    RequiresContextIOResult as RequiresContextIOResult,
+    RequiresContextIOResultE as RequiresContextIOResultE,
+)