Adds rescue and bind, fixes docs and tests

Author: sobolevn

CHANGELOG.md

@@ -25,9 +25,7 @@ See [0Ver](https://0ver.org/).
 - Adds `RequiresContextResult` container
 - Adds `RequiresContextResultE` alias
   for `RequiresContextResult[..., ..., Exception]`
-- Adds `RequiresContextResult` support for `bind`
-- Adds `RequiresContextResult` support for `flatten`
-- Adds `RequiresContextResult` support for `fold`
+- Adds `RequiresContextResult` support for `bind` and `rescue`
 
 - Adds `IOResult` helper to work better with `IO[Result[a, b]]`
 - Adds `IOResultE` alias for `IOResult[a, Exception]`

README.md

@@ -203,6 +203,9 @@ And now you can pass your dependencies in a really direct and explicit way.
 And have the type-safety to check what you pass to cover your back.
 Check out [RequiresContext](https://returns.readthedocs.io/en/latest/pages/context.html) docs for more. There you will learn how to make `'.'` also configurable.
 
+We also have [RequiresContextResult](https://returns.readthedocs.io/en/latest/pages/context.html#requirescontextresult-container)
+for context-related operations that might fail.
+
 
 ## Result container
 

docs/pages/container.rst

@@ -10,7 +10,7 @@ while maintaining the execution context.
 List of supported containers:
 
 - :class:`Maybe <returns.maybe.Maybe>` to handle ``None`` cases
-- :class:`RequiresContext <returns.context.RequiresContext>`
+- :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

docs/pages/context.rst

@@ -262,13 +262,13 @@ Which means that it is a wrapper around pure function that might fail.
 We also added a lot of useful methods for this container,
 so you can work easily with it:
 
-- :meth:`returns.context.RequiresContextResult.from_typecast` turns
-  accidental ``RequiresContext[env, Result[a, b]]`` into
+- :meth:`returns.context.requires_context.RequiresContextResult.from_typecast`
+  turns accidental ``RequiresContext[env, Result[a, b]]`` into
   full-featured ``RequiresContextResult[env, a, b]``
-- :meth:`returns.context.RequiresContextResult.bind_result` allows to bind
-  functions that return ``Result`` with just one call
-- :meth:returns.context.RequiresContextResult.bind_context` allows to bind
-  functions that return ``RequiresContext`` easily
+- :meth:`returns.context.requires_context.RequiresContextResult.bind_result`
+  allows to bind functions that return ``Result`` with just one call
+- :meth:returns.context.requires_context.RequiresContextResult.bind_context`
+  allows to bind functions that return ``RequiresContext`` easily
 - There are also several useful contructors from any possible type
 
 Use it when you work with pure context-related functions that might fail.
@@ -288,7 +288,6 @@ How can I access dependencies inside the context?
 
 
 
-
 Further reading
 ---------------
 

returns/_generated/pointfree/bind.pyi

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

returns/_generated/pointfree/rescue.pyi

@@ -4,12 +4,17 @@ from typing import Callable, TypeVar, overload
 
 from returns.io import IOResult
 from returns.result import Result
+from returns.context import RequiresContextResult
 
+# Result:
 _ValueType = TypeVar('_ValueType')
 _ErrorType = TypeVar('_ErrorType')
 _NewValueType = TypeVar('_NewValueType')
 _NewErrorType = TypeVar('_NewErrorType')
 
+# Context:
+_EnvType = TypeVar('_EnvType')
+
 
 @overload
 def _rescue(
@@ -29,3 +34,16 @@ def _rescue(
     IOResult[_ValueType, _NewErrorType],
 ]:
     ...
+
+
+@overload
+def _rescue(
+    function: Callable[
+        [_ErrorType],
+        RequiresContextResult[_EnvType, _ValueType, _NewErrorType],
+    ],
+) -> Callable[
+    [RequiresContextResult[_EnvType, _ValueType, _ErrorType]],
+    RequiresContextResult[_EnvType, _ValueType, _NewErrorType]
+]:
+    ...

returns/context/requires_context_result.py

@@ -28,12 +28,19 @@ class RequiresContextResult(
     """
     The ``RequiresContextResult`` combinator.
 
-    See :class:`returns.context.RequiresContext` for more docs.
+    See :class:`returns.context.requires_context.RequiresContext` for more docs.
 
     This is just a handy wrapper around ``RequiresContext[env, Result[a, b]]``
     which represents a context-dependent pure operation
     that might fail and return :class:`returns.result.Result`.
 
+    It has several important differences from the regular ``Result`` classes.
+    It does not have ``Success`` and ``Failure`` subclasses.
+    Because, the computation is not yet performed.
+    And we cannot know the type in advance.
+
+    So, this is a thin wrapper, without any changes in logic.
+
     Why do we need this wrapper? That's just for better usability!
 
     .. code:: python
@@ -60,18 +67,20 @@ class RequiresContextResult(
     - ``RequiresContext`` values and pure functions returning it
     - ``Result`` and functions returning it
 
-    See also:
-        https://dev.to/gcanti/getting-started-with-fp-ts-reader-1ie5
-        https://en.wikipedia.org/wiki/Lazy_evaluation
-        https://bit.ly/2R8l4WK
-        https://bit.ly/2RwP4fp
-
     Imporatant implementation detail:
     due it is meaning, ``RequiresContextResult``
     cannot have ``Success`` and ``Failure`` subclasses.
 
     We only have just one type. That's by design.
 
+    Different converters are also not supported for this type.
+
+    See also:
+        https://dev.to/gcanti/getting-started-with-fp-ts-reader-1ie5
+        https://en.wikipedia.org/wiki/Lazy_evaluation
+        https://bit.ly/2R8l4WK
+        https://bit.ly/2RwP4fp
+
     """
 
     #: This field has an extra 'RequiresContext' just because `mypy` needs it.

tests/test_pointfree/test_bind.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-from returns.context import RequiresContext
+from returns.context import RequiresContext, RequiresContextResult
 from returns.io import IO, IOFailure, IOResult, IOSuccess
 from returns.maybe import Maybe, Nothing, Some
 from returns.pointfree import bind
@@ -27,6 +27,12 @@ def _context_function(argument: int) -> RequiresContext[int, int]:
     return RequiresContext(lambda other: argument + other)
 
 
+def _context_result_function(
+    argument: int,
+) -> RequiresContextResult[int, int, str]:
+    return RequiresContextResult(lambda other: Success(argument + other))
+
+
 def test_bind_with_io():
     """Ensures that functions can be composed and return type is correct."""
     binded = bind(_io_function)
@@ -63,3 +69,10 @@ def test_bind_with_context():
     binded = bind(_context_function)
 
     assert binded(RequiresContext(lambda _: 3))(5) == 8
+
+
+def test_bind_with_context_result():
+    """Ensures that functions can be composed and return type is correct."""
+    binded = bind(_context_result_function)
+
+    assert binded(RequiresContextResult.from_success(3))(5) == Success(8)

tests/test_pointfree/test_rescue.py

@@ -3,6 +3,7 @@
 from returns.io import IOFailure, IOResult, IOSuccess
 from returns.pointfree import rescue
 from returns.result import Failure, Result, Success
+from returns.context import RequiresContextResult
 
 
 def _result_function(argument: int) -> Result[int, str]:
@@ -17,6 +18,14 @@ def _ioresult_function(argument: int) -> IOResult[int, str]:
     return IOFailure('nope')
 
 
+def _context_result_function(
+    argument: int,
+) -> RequiresContextResult[int, int, str]:
+    if argument > 0:
+        return RequiresContextResult(lambda deps: Success(argument + deps))
+    return RequiresContextResult.from_failure('nope')
+
+
 def test_rescue_with_ioresult():
     """Ensures that functions can be composed and return type is correct."""
     rescued = rescue(_ioresult_function)
@@ -33,3 +42,18 @@ def test_rescue_with_result():
     assert rescued(Success(1)) == Success(1)
     assert rescued(Failure(1)) == Success(2)
     assert rescued(Failure(0)) == Failure('nope')
+
+
+def test_rescue_with_context_result():
+    """Ensures that functions can be composed and return type is correct."""
+    rescued = rescue(_context_result_function)
+
+    assert rescued(
+        RequiresContextResult.from_success(1),
+    )(1) == Success(1)
+    assert rescued(
+        RequiresContextResult.from_failure(1),
+    )(1) == Success(2)
+    assert rescued(
+        RequiresContextResult.from_failure(0),
+    )(1) == Failure('nope')

typesafety/test_context/test_contest.yml renamed to typesafety/test_context/test_requires_context/test_contest.yml

@@ -3,20 +3,20 @@
   main: |
     from returns.context import Context
 
-    reveal_type(Context.ask())  # N: Revealed type is 'returns.context.RequiresContext[<nothing>, <nothing>]'
+    reveal_type(Context.ask())  # N: Revealed type is 'returns.context.requires_context.RequiresContext[<nothing>, <nothing>]'
 
 
 - case: context_ask2
   disable_cache: true
   main: |
     from returns.context import Context
 
-    reveal_type(Context[str].ask())  # N: Revealed type is 'returns.context.RequiresContext[builtins.str*, builtins.str*]'
+    reveal_type(Context[str].ask())  # N: Revealed type is 'returns.context.requires_context.RequiresContext[builtins.str*, builtins.str*]'
 
 
 - case: requires_context_from_value
   disable_cache: true
   main: |
     from returns.context import RequiresContext
 
-    reveal_type(RequiresContext.from_value(1))  # N: Revealed type is 'returns.context.RequiresContext[Any, builtins.int*]'
+    reveal_type(RequiresContext.from_value(1))  # N: Revealed type is 'returns.context.requires_context.RequiresContext[Any, builtins.int*]'