Closes #242

Author: sobolevn

CHANGELOG.md

@@ -49,6 +49,7 @@ See [0Ver](https://0ver.org/).
 - Adds `Unitable` protocol and `.from_success()` and `.from_failure()`
   methods for all `Result` realted classes
 - Adds `flow` function, which is similar to `pipe`
+- Adds `swap` coverter for `Result` and `IOResult`
 
 
 ### Bugfixes

docs/pages/converters.rst

@@ -12,25 +12,25 @@ Maybe and Result
 
 We have two converters to work with ``Result <-> Maybe`` tranformations:
 
-- ``maybe_to_result`` that converts ``Maybe`` to ``Result``
-- ``result_to_maybe`` that converts ``Result`` to ``Maybe``
+.. currentmodule:: returns.converters
+
+- :func:`~.maybe_to_result` that converts ``Maybe`` to ``Result``
+- :func:`~.result_to_maybe` that converts ``Result`` to ``Maybe``
 
 That's how they work:
 
 .. code:: python
 
   >>> from returns.converters import maybe_to_result, result_to_maybe
-  >>> from returns.maybe import Maybe
+  >>> from returns.maybe import Maybe, Some
   >>> from returns.result import Result, Success
 
   >>> result: Result[int, Exception] = Success(1)
   >>> maybe: Maybe[int] = result_to_maybe(result)
-  >>> str(maybe)
-  '<Some: 1>'
+  >>> assert maybe == Some(1)
 
   >>> new_result: Result[int, None] = maybe_to_result(maybe)
-  >>> str(new_result)
-  '<Success: 1>'
+  >>> assert new_result == Success(1)
 
 Take a note, that type changes.
 Also, take a note that ``Success(None)`` will be converted to ``Nothing``.
@@ -39,7 +39,9 @@ Also, take a note that ``Success(None)`` will be converted to ``Nothing``.
 flatten
 -------
 
-You can also use ``flatten`` to merge nested containers together:
+You can also use
+:func:`flatten <returns.converters.flatten>`
+to merge nested containers together:
 
 .. code:: python
 
@@ -53,12 +55,44 @@ You can also use ``flatten`` to merge nested containers together:
   >>> assert flatten(Success(Success(1))) == Success(1)
 
 
+swap
+----
+
+You can use :func:`swap <returns.converters.swap>`
+to swap value and error types in ``Result`` and ``IOResult`` containers.
+
+In other words: ``swap(Result[a, b]) == Result[b, a]``.
+
+This is useful for error handling and composition.
+Here's an example of how ``swap`` works:
+
+.. code:: python
+
+  >>> from returns.converters import swap
+  >>> from returns.io import IOSuccess, IOFailure
+  >>> from returns.result import Success, Failure
+
+  >>> assert swap(IOSuccess(1)) == IOFailure(1)
+  >>> assert swap(Failure(2)) == Success(2)
+
+You can use ``swap`` twice to get the same object back!
+
+.. code:: python
+
+  >>> from returns.converters import swap
+  >>> from returns.io import IOSuccess
+
+  >>> assert swap(swap(IOSuccess(1))) == IOSuccess(1)
+
+
 coalesce
 --------
 
-You can use :func:`returns.converters.coalesce_result`
-and :func:`returns.converters.coalesce_maybe` converters
-to covert containers to a regular value.
+You can use
+:func:`coalesce_result <returns.converters.coalesce_result>`,
+:func:`coalesce_ioresult <returns.converters.coalesce_ioresult>`,
+and :func:`coalesce_maybe <returns.converters.coalesce_maybe>`
+converters to covert containers to a regular value.
 
 These functions accept two functions:
 one for successful case, one for failing case.
@@ -70,9 +104,11 @@ one for successful case, one for failing case.
 
   >>> def handle_success(state: int) -> float:
   ...     return state / 2
+  ...
 
   >>> def handle_failure(state: str) -> float:
   ...     return 0.0
+  ...
 
   >>> coalesce_result(handle_success, handle_failure)(Success(1))
   0.5
@@ -83,5 +119,15 @@ one for successful case, one for failing case.
 API Reference
 -------------
 
+.. autofunction:: returns.converters.swap
+
+.. autofunction:: returns.converters.flatten
+
+.. autofunction:: returns.converters.coalesce_maybe
+
+.. autofunction:: returns.converters.coalesce_result
+
+.. autofunction:: returns.converters.coalesce_ioresult
+
 .. automodule:: returns.converters
    :members:

docs/pages/pipeline.rst

@@ -318,7 +318,11 @@ Further reading
 API Reference
 -------------
 
+.. autofunction:: returns.pipeline.flow
+
 .. autofunction:: returns.pipeline.pipe
 
+.. autofunction:: returns.pipeline.pipeline
+
 .. automodule:: returns.pipeline
    :members:

returns/_generated/converters/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

returns/_generated/coalesce.py renamed to returns/_generated/converters/coalesce.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+
+from typing import TypeVar, overload
+
+from returns.io import IOResult
+from returns.result import Result
+
+_ValueType = TypeVar('_ValueType')
+_ErrorType = TypeVar('_ErrorType')
+
+
+@overload
+def _swap(
+    container: Result[_ValueType, _ErrorType],
+) -> Result[_ErrorType, _ValueType]:
+    """Case for Result."""
+
+
+@overload
+def _swap(
+    container: IOResult[_ValueType, _ErrorType],
+) -> IOResult[_ErrorType, _ValueType]:
+    """Case for IOResult."""
+
+
+def _swap(container):
+    """
+    Swaps value and error types in a container.
+
+    Why? Because we have a lot of ``.bind`` related helpers
+    and none ``.rescue`` related helpers.
+
+    So, you can ``swap`` a container to handle errors in a simple way,
+    and then swap it back to continue normal execution.
+
+    .. code:: python
+
+      >>> from returns.converters import swap
+      >>> from returns.io import IOResult, IOSuccess, IOFailure
+
+      >>> container: IOResult[int, str] = IOSuccess(1)
+      >>> swapped: IOResult[str, int] = swap(container)
+      >>> assert swapped == IOFailure(1)
+
+      >>> container: IOResult[int, str] = IOFailure('error')
+      >>> assert swap(container) == IOSuccess('error')
+
+    And here's how you can handle errors easily:
+
+    .. code:: python
+
+      >>> from returns.converters import swap
+      >>> from returns.io import IOResult, IOSuccess
+      >>> from returns.result import Result, Success
+
+      >>> def function(error: str) -> Result[str, int]:
+      ...     return Success('Very bad error: ' + error)
+      ...
+
+      >>> container: IOResult[int, str] = IOFailure('boom')
+      >>> # You can `.rescue_result`, but you can `.bind_result` instead!
+      >>> assert swap(
+      ...     swap(container).bind_result(function),
+      ... ) == IOFailure('Very bad error: boom')
+
+    This converter supports only containers
+    that have ``.success_type`` property.
+
+    Basically ``Result`` and ``IOResult``.
+
+    """
+    if isinstance(container, container.success_type):
+        return container.bind(lambda inner: container.from_failure(inner))
+    return container.rescue(lambda inner: container.from_success(inner))

returns/_generated/flatten.py renamed to returns/_generated/converters/flatten.py

@@ -2,11 +2,15 @@
 
 from typing import TypeVar
 
-from returns._generated import coalesce
-from returns._generated.flatten import _flatten as flatten  # noqa: F401
+from returns._generated.converters import coalesce
+from returns._generated.converters.swap import _swap as swap  # noqa: F401
 from returns.maybe import Maybe
 from returns.result import Failure, Result, Success
 
+from returns._generated.converters.flatten import (  # isort:skip # noqa: F401
+    _flatten as flatten,
+)
+
 # Contianer internals:
 _ValueType = TypeVar('_ValueType')
 _ErrorType = TypeVar('_ErrorType')

returns/_generated/flatten.pyi renamed to returns/_generated/converters/flatten.pyi

@@ -39,6 +39,7 @@ def is_successful(container: '_Unwrapable') -> bool:
 
     This function can work with containers that support
     :class:`returns.primitives.interfaces.Unwrapable` protocol.
+    But only non-lazy containers are supported.
 
     """
     try:

returns/_generated/converters/swap.py

@@ -28,7 +28,7 @@
     (IOFailure(IOFailure('a')), IOFailure(IOFailure('a'))),
 ])
 def test_flatten(container, merged):
-    """Ensures that `join` is always returning the correct type."""
+    """Ensures that `flatten` is always returning the correct type."""
     assert flatten(container) == merged
 
 

returns/converters.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from returns.converters import swap
+from returns.io import IOFailure, IOSuccess
+from returns.result import Failure, Success
+
+
+@pytest.mark.parametrize(('container', 'swapped'), [
+    (Success({}), Failure({})),
+    (IOSuccess(1), IOFailure(1)),
+
+    (Failure({}), Success({})),
+    (IOFailure(1), IOSuccess(1)),
+])
+def test_swap_results(container, swapped):
+    """Ensures that `swap` is always returning the correct type."""
+    assert swap(container) == swapped
+
+
+@pytest.mark.parametrize('container', [
+    Success({}),
+    IOSuccess(1),
+
+    Failure('a'),
+    IOFailure(True),
+])
+def test_swap_twice(container):
+    """Ensures that `swap` is always returning the correct type."""
+    assert swap(swap(container)) == container

returns/pipeline.py

@@ -1,4 +1,4 @@
-- case: join_io
+- case: flatten_io
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -7,7 +7,7 @@
     reveal_type(flatten(IO(IO(1))))  # N: Revealed type is 'returns.io.IO[builtins.int*]'
 
 
-- case: join_maybe
+- case: flatten_maybe
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -16,7 +16,7 @@
     reveal_type(flatten(Some(Some(1))))  # N: Revealed type is 'returns.maybe.Maybe[builtins.int*]'
 
 
-- case: join_result1
+- case: flatten_result1
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -28,7 +28,7 @@
     reveal_type(flatten(returns_result()))  # N: Revealed type is 'returns.result.Result[builtins.int*, builtins.str*]'
 
 
-- case: join_result2
+- case: flatten_result2
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -42,7 +42,7 @@
     main:7: error: Argument 1 to "_flatten" has incompatible type "Result[int, Result[int, str]]"; expected "Result[Result[<nothing>, Result[int, str]], Result[int, str]]"
 
 
-- case: join_ioresult1
+- case: flatten_ioresult1
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -54,7 +54,7 @@
     reveal_type(flatten(returns_ioresult()))  # N: Revealed type is 'returns.io.IOResult[builtins.int*, builtins.str*]'
 
 
-- case: join_ioresult2
+- case: flatten_ioresult2
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -68,7 +68,7 @@
     main:7: error: Argument 1 to "_flatten" has incompatible type "IOResult[int, IOResult[int, str]]"; expected "IOResult[IOResult[<nothing>, IOResult[int, str]], IOResult[int, str]]"
 
 
-- case: join_context
+- case: flatten_context
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -79,7 +79,7 @@
     reveal_type(flatten(x))  # N: Revealed type is 'returns.context.requires_context.RequiresContext[builtins.str*, builtins.int*]'
 
 
-- case: join_context_result
+- case: flatten_context_result
   disable_cache: true
   main: |
     from returns.converters import flatten
@@ -88,3 +88,14 @@
     x: RequiresContextResult[str, RequiresContextResult[str, int, float], float]
 
     reveal_type(flatten(x))  # N: Revealed type is 'returns.context.requires_context_result.RequiresContextResult[builtins.str*, builtins.int*, builtins.float*]'
+
+
+- case: flatten_context_io_result
+  disable_cache: true
+  main: |
+    from returns.converters import flatten
+    from returns.context import RequiresContextIOResult
+
+    x: RequiresContextIOResult[str, RequiresContextIOResult[str, int, float], float]
+
+    reveal_type(flatten(x))  # N: Revealed type is 'returns.context.requires_context_io_result.RequiresContextIOResult[builtins.str*, builtins.int*, builtins.float*]'