add map_failure method (#91)

* add `map_failure` method

* fix tests, fix linter

* Update container.py

Author: astynax

docs/pages/container.rst

@@ -140,12 +140,13 @@ Returning execution to the right track
 We also support two special methods to work with "failed"
 types like ``Failure``:
 
-- :func:`.fix <returns.primitives.container.Fixable.fix>`
-  is the opposite of ``map`` method
-  that works only when container is in failed state
 - :func:`.rescue <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>`
+  transforms error to value (failure became success)
+  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:
@@ -157,6 +158,9 @@ during the pipeline execution:
   def double(state: int) -> float:
       return state * 2.0
 
+  result: Result[Any, float] = Failure(1).map_error(double)
+  # => Failure(2.0)
+
   result: Result[float, int] = Failure(1).fix(double)
   # => Success(2.0)
 

returns/primitives/container.py

@@ -95,10 +95,10 @@ class Fixable(Protocol[_ValueType, _ErrorType]):
     """Represents containers that can be fixed and rescued."""
 
     def fix(
-        self, function: Callable[[_ErrorType], _NewErrorType],
-    ) -> 'Fixable[_ValueType, _NewErrorType]':
+        self, function: Callable[[_ErrorType], _NewValueType],
+    ) -> 'Fixable[_NewValueType, _ErrorType]':
         """
-        Applies 'function' to the contents of the functor.
+        Applies 'function' to the error and transforms failure to success.
 
         And returns a new functor value.
         Works for containers that represent failure.
@@ -130,6 +130,18 @@ 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]):

returns/result.py

@@ -81,7 +81,7 @@ def failure(self) -> _ErrorType:  # pragma: no cover
         raise NotImplementedError()
 
 
-@final
+@final  # noqa: Z214
 class _Failure(Result[Any, _ErrorType]):
     """
     Represents a calculation which has failed.
@@ -100,6 +100,17 @@ def map(self, function):  # noqa: A003
         """Returns the '_Failure' instance that was used to call the method."""
         return self
 
+    def map_failure(self, function):
+        """
+        Applies function to the error value.
+
+        Applies 'function' to the contents of the '_Failure' instance
+        and returns a new '_Failure' object containing the result.
+        'function' should accept a single "normal" (non-container) argument
+        and return a non-container result.
+        """
+        return _Failure(function(self._inner_value))
+
     def bind(self, function):
         """Returns the '_Failure' instance that was used to call the method."""
         return self
@@ -140,7 +151,7 @@ def failure(self):
         return self._inner_value
 
 
-@final
+@final  # noqa: Z214
 class _Success(Result[_ValueType, Any]):
     """
     Represents a calculation which has succeeded and contains the result.
@@ -166,6 +177,10 @@ def map(self, function):  # noqa: A003
         """
         return _Success(function(self._inner_value))
 
+    def map_failure(self, function):
+        """Returns the '_Success' instance that was used to call the method."""
+        return self
+
     def bind(self, function):
         """
         Applies 'function' to the result of a previous calculation.

tests/test_result/test_result_map.py

@@ -4,20 +4,20 @@
 
 
 def test_map_success():
-    """Ensures that Failure identity works for Success container."""
+    """Ensures that Success is mappable."""
     assert Success(5).map(str) == Success('5')
 
 
 def test_map_failure():
-    """Ensures that Failure identity works for Success container."""
-    assert Failure(5).map(str) == Failure(5)
+    """Ensures that Failure is mappable."""
+    assert Failure(5).map_failure(str) == Failure('5')
 
 
 def test_fix_success():
-    """Ensures that Failure identity works for Success container."""
+    """Ensures that Success.fix is NoOp."""
     assert Success(5).fix(str) == Success(5)
 
 
 def test_fix_failure():
-    """Ensures that Failure identity works for Success container."""
+    """Ensures that Failure.fix produces the Success."""
     assert Failure(5).fix(str) == Success('5')