Closes #196

Author: sobolevn

CHANGELOG.md

@@ -13,6 +13,7 @@ See (0Ver)[https://0ver.org/].
 - **Breaking**: now `@pipeline` requires a container type when created:
   `@pipeline(Result)` or `@pipeline(Maybe)`
 - `Maybe` and `Result` now has `success_type` and `failure_type` aliases
+- Adds `Result.unify` utility method for better error type composition
 - We now support `dry-python/classes` as a first-class citizen
 - Adds `io_squash` to squash several `IO` containers into one container
   with a tuple inside, currently works with `9` containers max at a time

docs/pages/result.rst

@@ -136,6 +136,30 @@ That's why we have public
 type constructor functions: ``Success`` and ``Failure``
 and internal implementation.
 
+How to compose error types?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You might want to sometimes use ``.unify`` instead of ``.bind``
+to compose error types together.
+While ``.bind`` enforces error type to stay the same,
+``.unify`` is designed
+to return a ``Union`` of a revious error type and a new one.
+
+Like so:
+
+.. code:: python
+
+  from returns.result import Result
+
+  def div(number: int) -> Result[float, ZeroDivisionError]:
+      return 1 / number
+
+  container: Result[int, ValueError]
+  container.unify(div)
+  # => Revealed type is: Result[float, Union[ValueError, ZeroDivisionError]]
+
+So, that's a way to go, if you need this composition.
+
 
 API Reference
 -------------

returns/result.py

@@ -62,6 +62,22 @@ def bind(
         """Abstract method to compose a container with another container."""
         raise NotImplementedError
 
+    def unify(
+        self,
+        function: Callable[
+            [_ValueType], 'Result[_NewValueType, _NewErrorType]',
+        ],
+    ) -> 'Result[_NewValueType, Union[_ErrorType, _NewErrorType]]':
+        """
+        Abstract method to compose a container with another container.
+
+        Similar to ``.bind``, but unifies the error type into a new type.
+        It is useful when you have several functions to compose
+        and each of them raises their own exceptions.
+        That's a way to collect all of them.
+        """
+        raise NotImplementedError
+
     def fix(
         self,
         function: Callable[[_ErrorType], _NewValueType],
@@ -160,6 +176,21 @@ def bind(self, function):
         """
         return self
 
+    def unify(self, function):
+        """
+        Returns the '_Failure' instance that was used to call the method.
+
+        .. code:: python
+
+          >>> def bindable(string: str) -> Result[str, str]:
+          ...      return Success(string + 'b')
+          ...
+          >>> Failure('a').unify(bindable) == Failure('a')
+          True
+
+        """
+        return self
+
     def fix(self, function):
         """
         Applies function to the inner value.
@@ -312,6 +343,29 @@ def bind(self, function):
         """
         return function(self._inner_value)
 
+    def unify(self, function):
+        """
+        Applies 'function' to the result of a previous calculation.
+
+        It is the same as ``.bind``, but handles type signatures differently.
+        While ``.bind`` forces to respect error type and not changing it,
+        ``.unify`` allows to return a ``Union`` of previous
+        error types and new ones.
+
+        'function' should accept a single "normal" (non-container) argument
+        and return Result a '_Failure' or '_Success' type object.
+
+        .. code:: python
+
+          >>> def bindable(string: str) -> Result[str, str]:
+          ...      return Success(string + 'b')
+          ...
+          >>> Success('a').bind(bindable) == Success('ab')
+          True
+
+        """
+        return self.bind(function)  # type: ignore
+
     def fix(self, function):
         """
         Returns the '_Success' instance that was used to call the method.

tests/test_result/test_result_base.py

@@ -7,6 +7,7 @@
 
 @pytest.mark.parametrize('method_name', [
     'bind',
+    'unify',
     'map',
     'rescue',
     'fix',

tests/test_result/test_result_bind.py

@@ -34,6 +34,17 @@ def factory(inner_value: int) -> Result[int, str]:
     assert bound.bind(factory) == factory(input_value)
 
 
+def test_unify_and_bind():
+    """Ensures that left identity works for Success container."""
+    def factory(inner_value: int) -> Result[int, str]:
+        return Success(inner_value * 2)
+
+    bound: Result[int, str] = Success(5)
+
+    assert bound.unify(factory) == bound.bind(factory)
+    assert bound.bind(factory) == bound.unify(factory)
+
+
 def test_left_identity_failure():
     """Ensures that left identity works for Failure container."""
     def factory(inner_value: int) -> Result[int, int]:
@@ -43,6 +54,7 @@ def factory(inner_value: int) -> Result[int, int]:
     bound: Result[int, int] = Failure(input_value)
 
     assert bound.bind(factory) == Failure(input_value)
+    assert bound.unify(factory) == Failure(input_value)
     assert str(bound) == '<Failure: 5>'
 
 

typesafety/test_result/test_success.yml

@@ -10,6 +10,44 @@
     reveal_type(first.bind(returns_result))  # N: Revealed type is 'returns.result.Result[builtins.str*, builtins.Exception]'
 
 
+- case: success_unify1
+  disable_cache: true
+  main: |
+    from returns.result import Success, Result
+
+    def returns_result(param: int) -> Result[str, TypeError]:
+        ...
+
+    first: Result[int, ValueError] = Success(1)
+    reveal_type(first.unify(returns_result))  # N: Revealed type is 'returns.result.Result[builtins.str*, Union[builtins.ValueError, builtins.TypeError*]]'
+
+
+- case: success_unify2
+  disable_cache: true
+  main: |
+    from typing import Union
+    from returns.result import Success, Result
+
+    def returns_result(param: int) -> Result[str, TypeError]:
+        ...
+
+    first: Result[int, Union[ValueError, KeyError]] = Success(1)
+    reveal_type(first.unify(returns_result))  # N: Revealed type is 'returns.result.Result[builtins.str*, Union[builtins.ValueError, builtins.KeyError, builtins.TypeError*]]'
+
+
+- case: success_unify3
+  disable_cache: true
+  main: |
+    from typing import Union
+    from returns.result import Success, Result
+
+    def returns_result(param: int) -> Result[str, Union[KeyError, TypeError]]:
+        ...
+
+    first: Result[int, ValueError] = Success(1)
+    reveal_type(first.unify(returns_result))  # N: Revealed type is 'returns.result.Result[builtins.str*, Union[builtins.ValueError, builtins.KeyError, builtins.TypeError]]'
+
+
 - case: success_map
   disable_cache: true
   main: |