Closes #96, closes #106, closes #105

Author: sobolevn

CHANGELOG.md

@@ -8,6 +8,8 @@ We follow Semantic Versions since the `0.1.0` release.
 ### Features
 
 - Provides a bunch of primitive interfaces to write your own containers
+- Adds `.map_failure()` method
+- Adds `join()` function to join nested containers
 
 ### Bugfixes
 

docs/pages/container.rst

@@ -50,7 +50,7 @@ The difference is simple:
 - ``map`` works with functions that return regular value
 - ``bind`` works with functions that return new container of the same type
 
-:func:`.bind <returns.primitives.container.Bindable.bind>`
+:func:`~returns.primitives.container.Bindable.bind`
 is used to literally bind two different containers together.
 
 .. code:: python
@@ -63,7 +63,7 @@ is used to literally bind two different containers together.
   # Can be assumed as either Success[int] or Failure[str]:
   result: Result[int, str] = Success(1).bind(may_fail)
 
-And we have :func:`.map <returns.primitives.container.Mappable.map>`
+And we have :func:`~returns.primitives.container.Mappable.map`
 to use containers with regular functions.
 
 .. code:: python
@@ -140,13 +140,17 @@ Returning execution to the right track
 We also support two special methods to work with "failed"
 types like ``Failure``:
 
-- :func:`.rescue <returns.primitives.container.Rescueable.rescue>`
+- :func:`~returns.primitives.container.Rescueable.rescue`
   is the opposite of ``bind`` method
   that works only when container is in failed state
-- :func:`.fix <returns.primitives.container.Fixable.fix>`
+- :func:`~returns.primitives.container.Fixable.fix`
   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.map_failure`
+  transforms error to another error
+  that works only when container is in failed state,
+  is the opposite of ``map`` method
 
 ``fix`` can be used to fix some fixable errors
 during the pipeline execution:
@@ -158,7 +162,7 @@ during the pipeline execution:
   def double(state: int) -> float:
       return state * 2.0
 
-  result: Result[Any, float] = Failure(1).map_error(double)
+  result: Result[Any, float] = Failure(1).map_failure(double)
   # => Failure(2.0)
 
   result: Result[float, int] = Failure(1).fix(double)
@@ -301,20 +305,26 @@ You can and should compose different containers together.
 Here's the full table of compositions that make sense:
 
 - ``IO[Result[A, B]]`` ✅
-- ``Result[IO[A], B]`` ✅
 - ``IO[Maybe[A]]`` ✅
-- ``Maybe[IO[A]]`` ✅
-- ``IO[IO[A]]`` 🚫
+- ``IO[IO[A]]`` 🤔, use :func:`join <returns.converters.join>`
+- ``Maybe[Maybe[A]]`` 🤔, use :func:`join <returns.converters.join>`
+- ``Result[Result[A, B], C]`` 🤔, use :func:`join <returns.converters.join>`
+- ``Result[Maybe[A], B]`` 🤔,
+    use :func:`maybe_to_result <returns.converters.maybe_to_result>`
+- ``Maybe[Result[A, B]]`` 🤔,
+    use :func:`result_to_maybe <returns.converters.result_to_maybe>`
+- ``Result[IO[A], B]`` 🚫
 - ``Result[A, IO[A]]`` 🚫
-- ``Result[Maybe[A], B]`` 🚫
 - ``Result[A, Maybe[B]]`` 🚫
-- ``Result[Result[A, B], C]`` 🚫
 - ``Result[A, Result[B, C]]`` 🚫
-- ``Maybe[Result[A, B]]`` 🚫
+- ``Maybe[IO[A]]`` 🚫
 
 You can use :ref:`converters` to convert ``Maybe`` and ``Result`` containers.
 So, you don't have to compose them.
 
+You can also use :func:`join <returns.converters.join>`
+to merge nested containers.
+
 
 .. _converters:
 
@@ -342,6 +352,19 @@ That's how they work:
 Take a note, that type changes.
 Also, take a note that ``Success(None)`` will be converted to ``Nothing``.
 
+You can also use ``join`` to merge nested containers together:
+
+.. code:: python
+
+  from returns.converters import join
+  from returns.maybe import Maybe
+  from returns.result import Success
+  from returns.io import IO
+
+  assert join(IO(IO(1))) == IO(1)
+  assert Maybe(Maybe(1)) == Maybe(1)
+  assert Success(Success(1)) == Success(1)
+
 
 API Reference
 -------------
@@ -350,3 +373,6 @@ API Reference
 
 .. automodule:: returns.primitives.container
    :members:
+
+.. automodule:: returns.converters
+   :members:

poetry.lock

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 
-from typing import TypeVar
+from typing import TypeVar, overload
 
+from returns.io import IO
 from returns.maybe import Maybe
 from returns.result import Failure, Result, Success
 
@@ -24,3 +25,25 @@ def maybe_to_result(
     if inner_value is not None:
         return Success(inner_value)
     return Failure(inner_value)
+
+
+@overload
+def join(container: IO[IO[_ValueType]]) -> IO[_ValueType]:
+    """Case for ``IO`` container."""
+
+
+@overload
+def join(container: Maybe[Maybe[_ValueType]]) -> Maybe[_ValueType]:
+    """Case for ``Maybe`` container."""
+
+
+@overload
+def join(
+    container: Result[Result[_ValueType, _ErrorType], _ErrorType],
+) -> Result[_ValueType, _ErrorType]:
+    """Case for ``Result`` container."""
+
+
+def join(container):
+    """Joins two nested containers together."""
+    return container._inner_value  # noqa: Z441

returns/converters.py

@@ -130,18 +130,6 @@ def rescue(
         Is the opposite of :meth:`~bind`.
         """
 
-    def map_failure(
-        self, 
-        function: Callable[[_ErrorType], _NewErrorType],
-    ) -> 'Fixable[_ValueType, _NewErrorType]':
-        """
-        Uses 'function' to transform one error to another.
-
-        And returns a new functor value.
-        Works for containers that represent failure.
-        Is the opposite of :meth:`~map`.
-        """
-
 
 @runtime
 class Unwrapable(Protocol[_ValueType]):
@@ -167,6 +155,18 @@ def unwrap(self) -> _ValueType:
 class UnwrapableFailure(Protocol[_ValueType, _ErrorType]):
     """Allows to unwrap failures."""
 
+    def map_failure(
+        self,
+        function: Callable[[_ErrorType], _NewErrorType],
+    ) -> 'Fixable[_ValueType, _NewErrorType]':
+        """
+        Uses 'function' to transform one error to another.
+
+        And returns a new functor value.
+        Works for containers that represent failure.
+        Is the opposite of :meth:`~map`.
+        """
+
     def failure(self) -> _ErrorType:
         """
         Custom magic method to unwrap inner value from the failed container.

returns/primitives/container.py

@@ -52,6 +52,14 @@ def fix(
         """Abstract method to compose container with pure function."""
         raise NotImplementedError()
 
+    @abstractmethod
+    def map_failure(
+        self,
+        function: Callable[[_ErrorType], _NewErrorType],
+    ) -> 'Result[_ValueType, _NewErrorType]':  # pragma: no cover
+        """Abstract method to compose container with pure function."""
+        raise NotImplementedError()
+
     @abstractmethod
     def rescue(
         self,