Adds RequiresContextResult combinator

Author: sobolevn

docs/pages/railway.rst

@@ -64,7 +64,7 @@ types like ``Failure``:
   transforms error to value (failure became success)
   that works only when container is in failed state,
   is the opposite of ``map`` method
-- :func:`~returns.primitives.container.UnwrapableFailure.alt`
+- :func:`~returns.primitives.container.Altable.alt`
   transforms error to another error
   that works only when container is in failed state,
   is the opposite of ``map`` method

returns/_generated/pointfree/rescue.pyi

@@ -2,9 +2,9 @@
 
 from typing import Callable, TypeVar, overload
 
+from returns.context import RequiresContextResult
 from returns.io import IOResult
 from returns.result import Result
-from returns.context import RequiresContextResult
 
 # Result:
 _ValueType = TypeVar('_ValueType')
@@ -44,6 +44,6 @@ def _rescue(
     ],
 ) -> Callable[
     [RequiresContextResult[_EnvType, _ValueType, _ErrorType]],
-    RequiresContextResult[_EnvType, _ValueType, _NewErrorType]
+    RequiresContextResult[_EnvType, _ValueType, _NewErrorType],
 ]:
     ...

returns/context/requires_context_result.py

@@ -74,6 +74,7 @@ class RequiresContextResult(
     We only have just one type. That's by design.
 
     Different converters are also not supported for this type.
+    Use converters inside the ``RequiresContext`` context, not outside.
 
     See also:
         https://dev.to/gcanti/getting-started-with-fp-ts-reader-1ie5

returns/primitives/container.py

@@ -171,7 +171,7 @@ def failure(self) -> _ErrorType:
 
 
 @runtime
-class UnwrapableFailure(Protocol[_ValueType, _ErrorType]):
+class Altable(Protocol[_ValueType, _ErrorType]):
     """Allows to unwrap failures."""
 
     def alt(

tests/test_context/test_context.py renamed to tests/test_context/test_requires_context/test_context.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from returns.context import ContextResult, RequiresContextResult
+from returns.primitives.container import (
+    Altable,
+    Bindable,
+    Fixable,
+    Mappable,
+    Rescueable,
+    Unwrapable,
+)
+from returns.result import Failure, Success
+
+
+@pytest.mark.parametrize('container', [
+    RequiresContextResult(lambda _: Success(1)),
+    RequiresContextResult(lambda _: Failure(1)),
+    RequiresContextResult.from_success(1),
+    RequiresContextResult.from_failure(1),
+    ContextResult.ask(),
+])
+@pytest.mark.parametrize('protocol', [
+    Bindable,
+    Mappable,
+    Rescueable,
+    Unwrapable,
+    Altable,
+    Fixable,
+])
+def test_protocols(container, protocol):
+    """Ensures that RequiresContext has all the right protocols."""
+    assert isinstance(container, protocol)
+
+
+def test_context_map():
+    """Ensures that RequiresContext container supports ``.map()`` method."""
+    context = RequiresContextResult.from_success(1.0).map(str)
+    assert context(...) == RequiresContextResult.from_success(
+        '1.0',
+    )(RequiresContextResult.empty)

tests/test_context/test_context_equality.py renamed to tests/test_context/test_requires_context/test_context_equality.py

@@ -0,0 +1,80 @@
+# -*- coding: utf-8 -*-
+
+from returns.context import RequiresContext
+from returns.context import RequiresContextResult as RCR  # noqa: N814
+from returns.result import Failure, Result, Success
+
+
+def test_bind():
+    """Ensures that bind works."""
+    def factory(inner_value: int) -> RCR[int, float, str]:
+        if inner_value > 0:
+            return RCR(lambda deps: Success(inner_value / deps))
+        return RCR.from_failure(str(inner_value))
+
+    input_value = 5
+    bound: RCR[int, int, str] = RCR.from_success(input_value)
+    assert bound.bind(factory)(2) == factory(input_value)(2)
+    assert bound.bind(factory)(2) == Success(2.5)
+
+    assert RCR.from_success(0).bind(
+        factory,
+    )(2) == factory(0)(2) == Failure('0')
+
+
+def test_bind_regular_result():
+    """Ensures that regular ``Result`` can be bound to ``IOResult``."""
+    def factory(inner_value: int) -> Result[int, str]:
+        if inner_value > 0:
+            return Success(inner_value + 1)
+        return Failure('nope')
+
+    first: RCR[int, int, str] = RCR.from_success(1)
+    third: RCR[int, int, str] = RCR.from_failure('a')
+
+    assert first.bind_result(factory)(RCR.empty) == Success(2)
+    assert RCR.from_success(0).bind_result(
+        factory,
+    )(RCR.empty) == Failure('nope')
+    assert third.bind_result(factory)(RCR.empty) == Failure('a')
+
+
+def test_bind_regular_context():
+    """Ensures that regular ``Result`` can be bound to ``IOResult``."""
+    def factory(inner_value: int) -> RequiresContext[int, float]:
+        return RequiresContext(lambda deps: inner_value / deps)
+
+    first: RCR[int, int, str] = RCR.from_success(1)
+    third: RCR[int, int, str] = RCR.from_failure('a')
+
+    assert first.bind_context(factory)(2) == Success(0.5)
+    assert RCR.from_success(2).bind_context(
+        factory,
+    )(1) == Success(2.0)
+    assert third.bind_context(factory)(1) == Failure('a')
+
+
+def test_rescue_success():
+    """Ensures that rescue works for Success container."""
+    def factory(inner_value) -> RCR[int, int, str]:
+        return RCR.from_success(inner_value * 2)
+
+    assert RCR.from_success(5).rescue(
+        factory,
+    )(0) == RCR.from_success(5)(0)
+    assert RCR.from_failure(5).rescue(
+        factory,
+    )(0) == RCR.from_success(10)(0)
+
+
+def test_rescue_failure():
+    """Ensures that rescue works for Failure container."""
+    def factory(inner_value) -> RCR[int, int, str]:
+        return RCR.from_failure(inner_value * 2)
+
+    assert RCR.from_success(5).rescue(
+        factory,
+    )(0) == RCR.from_success(5)(0)
+    assert RCR.from_failure(5).rescue(
+        factory,
+    )(0) == RCR.from_failure(10)(0)

tests/test_context/test_context_utils.py renamed to tests/test_context/test_requires_context/test_context_utils.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+from returns.context import RequiresContextResult, RequiresContextResultE
+
+
+def _function(arg: int) -> RequiresContextResultE[int, float]:
+    if arg == 0:
+        return RequiresContextResult.from_failure(
+            ZeroDivisionError('Divided by 0'),
+        )
+    return RequiresContextResult.from_success(10 / arg)
+
+
+def test_requires_context_resulte():
+    """Ensures that RequiresContextResultE correctly typecast."""
+    container: RequiresContextResult[int, float, Exception] = _function(1)
+    assert container(0) == RequiresContextResult.from_success(10.0)(0)