Closes #252

Author: sobolevn

docs/pages/converters.rst

@@ -53,19 +53,19 @@ You can also use ``flatten`` to merge nested containers together:
   >>> assert flatten(Success(Success(1))) == Success(1)
 
 
-fold
-----
+coalesce
+--------
 
-You can use :func:`returns.converters.fold_result`
-and :func:`returns.converters.fold_maybe` converters
+You can use :func:`returns.converters.coalesce_result`
+and :func:`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.
 
 .. code:: python
 
-  >>> from returns.converters import fold_result
+  >>> from returns.converters import coalesce_result
   >>> from returns.result import Success, Failure
 
   >>> def handle_success(state: int) -> float:
@@ -74,9 +74,9 @@ one for successful case, one for failing case.
   >>> def handle_failure(state: str) -> float:
   ...     return 0.0
 
-  >>> fold_result(handle_success, handle_failure)(Success(1))
+  >>> coalesce_result(handle_success, handle_failure)(Success(1))
   0.5
-  >>> fold_result(handle_success, handle_failure)(Failure(1))
+  >>> coalesce_result(handle_success, handle_failure)(Failure(1))
   0.0
 
 

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

@@ -7,34 +7,34 @@
 and second one for failed containers like ``Nothing`` and ``Failure``.
 
 This function is useful when you need
-to fold two possible container states into one type.
+to coalesce two possible container states into one type.
 
 Note::
-    ``IOResult`` only fold to ``IO`` values.
+    ``IOResult`` only coalesce to ``IO`` values.
     It is impossible to unwrap ``IO`` here.
 
 .. code:: python
 
-    >>> from returns.converters import fold_result
+    >>> from returns.converters import coalesce_result
     >>> from returns.result import Success, Failure
     >>> f1 = lambda x: x + 1
     >>> f2 = lambda y: y + 'b'
-    >>> assert fold_result(f1, f2)(Success(1)) == 2
-    >>> assert fold_result(f1, f2)(Failure('a')) == 'ab'
+    >>> assert coalesce_result(f1, f2)(Success(1)) == 2
+    >>> assert coalesce_result(f1, f2)(Failure('a')) == 'ab'
 
-    >>> from returns.converters import fold_ioresult
+    >>> from returns.converters import coalesce_ioresult
     >>> from returns.io import IO, IOSuccess, IOFailure
     >>> f1 = lambda x: x.map(lambda state: state + 1)
     >>> f2 = lambda y: y.map(lambda state: state + 'b')
-    >>> assert fold_result(f1, f2)(IOSuccess(1)) == IO(2)
-    >>> assert fold_result(f1, f2)(IOFailure('a')) == IO('ab')
+    >>> assert coalesce_result(f1, f2)(IOSuccess(1)) == IO(2)
+    >>> assert coalesce_result(f1, f2)(IOFailure('a')) == IO('ab')
 
-    >>> from returns.converters import fold_maybe
+    >>> from returns.converters import coalesce_maybe
     >>> from returns.maybe import Some, Nothing
     >>> f1 = lambda x: x + 1
     >>> f2 = lambda _: 'a'
-    >>> assert fold_maybe(f1, f2)(Some(1)) == 2
-    >>> assert fold_maybe(f1, f2)(Nothing) == 'a'
+    >>> assert coalesce_maybe(f1, f2)(Some(1)) == 2
+    >>> assert coalesce_maybe(f1, f2)(Nothing) == 'a'
 
 """
 
@@ -66,29 +66,29 @@ def decorator(container):
     return decorator
 
 
-_fold_result: Callable[
+_coalesce_result: Callable[
     [
         Callable[[_ValueType], _FirstType],
         Callable[[_ErrorType], _FirstType],
     ],
     Callable[[Result[_ValueType, _ErrorType]], _FirstType],
 ] = _fold
-_fold_result.__doc__ = __doc__
+_coalesce_result.__doc__ = __doc__
 
-_fold_ioresult: Callable[
+_coalesce_ioresult: Callable[
     [
         Callable[[IO[_ValueType]], IO[_FirstType]],
         Callable[[IO[_ErrorType]], IO[_FirstType]],
     ],
     Callable[[IOResult[_ValueType, _ErrorType]], IO[_FirstType]],
 ] = _fold
-_fold_ioresult.__doc__ = __doc__
+_coalesce_ioresult.__doc__ = __doc__
 
-_fold_maybe: Callable[
+_coalesce_maybe: Callable[
     [
         Callable[[_ValueType], _FirstType],
         Callable[[None], _FirstType],
     ],
     Callable[[Maybe[_ValueType]], _FirstType],
 ] = _fold
-_fold_maybe.__doc__ = __doc__
+_coalesce_maybe.__doc__ = __doc__

returns/converters.py

@@ -2,7 +2,7 @@
 
 from typing import TypeVar
 
-from returns._generated import fold
+from returns._generated import coalesce
 from returns._generated.flatten import _flatten as flatten  # noqa: F401
 from returns.maybe import Maybe
 from returns.result import Failure, Result, Success
@@ -12,9 +12,9 @@
 _ErrorType = TypeVar('_ErrorType')
 
 # Re-export from generated:
-fold_maybe = fold._fold_maybe  # noqa: WPS437
-fold_result = fold._fold_result  # noqa: WPS437
-fold_ioresult = fold._fold_ioresult  # noqa: WPS437
+coalesce_maybe = coalesce._coalesce_maybe  # noqa: WPS437
+coalesce_result = coalesce._coalesce_result  # noqa: WPS437
+coalesce_ioresult = coalesce._coalesce_ioresult  # noqa: WPS437
 
 
 def result_to_maybe(

returns/functions.py

@@ -22,17 +22,17 @@ def identity(instance: _FirstType) -> _FirstType:
     Why do we even need this?
     Identity functions help us with the composition.
 
-    Imagine, that you want to use :func:`returns.converters.fold_result`
+    Imagine, that you want to use :func:`returns.converters.coalesce_result`
     like so:
 
     .. code:: python
 
       from returns.result import Result
-      from returns.converters import fold_result
+      from returns.converters import coalesce_result
 
       numbers: Result[int, float]
-      # Now you want to fold `number` into `int` type:
-      number: int = fold_result(identity, int)(numbers)
+      # Now you want to coalesce `number` into `int` type:
+      number: int = coalesce_result(identity, int)(numbers)
       # Done!
 
     See also:

tests/test_converters/test_fold.py renamed to tests/test_converters/test_coalesce.py

@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
 
-from returns.converters import fold_ioresult, fold_maybe, fold_result
+from returns.converters import (
+    coalesce_ioresult,
+    coalesce_maybe,
+    coalesce_result,
+)
 from returns.io import IO, IOFailure, IOSuccess
 from returns.maybe import Nothing, Some
 from returns.result import Failure, Success
@@ -14,27 +18,27 @@ def _failed_case(_) -> int:
     return 0
 
 
-_result_converter = fold_result(_success_case, _failed_case)
-_maybe_converter = fold_maybe(_success_case, _failed_case)
-_ioresult_converter = fold_ioresult(
+_result_converter = coalesce_result(_success_case, _failed_case)
+_maybe_converter = coalesce_maybe(_success_case, _failed_case)
+_ioresult_converter = coalesce_ioresult(
     IO.lift(_success_case),
     IO.lift(_failed_case),
 )
 
 
-def test_fold_result():
-    """Ensures that `fold` is always returning the correct type."""
+def test_coalesce_result():
+    """Ensures that `coalesce` is always returning the correct type."""
     assert _result_converter(Success(1)) == 2
     assert _result_converter(Failure(1)) == 0
 
 
-def test_fold_ioresult():
-    """Ensures that `fold` is always returning the correct type."""
+def test_coalesce_ioresult():
+    """Ensures that `coalesce` is always returning the correct type."""
     assert _ioresult_converter(IOSuccess(1)) == IO(2)
     assert _ioresult_converter(IOFailure(1)) == IO(0)
 
 
-def test_fold_maybe():
-    """Ensures that `fold` is always returning the correct type."""
+def test_coalesce_maybe():
+    """Ensures that `coalesce` is always returning the correct type."""
     assert _maybe_converter(Some(2)) == 3
     assert _maybe_converter(Nothing) == 0

typesafety/test_converters/test_fold.yml renamed to typesafety/test_converters/test_coalesce.yml

@@ -1,7 +1,7 @@
-- case: fold_result
+- case: coalesce_result
   disable_cache: true
   main: |
-    from returns.converters import fold_result
+    from returns.converters import coalesce_result
     from returns.result import Result
 
     def first(arg: int) -> float:
@@ -11,13 +11,13 @@
         ...
 
     container: Result[int, str]
-    reveal_type(fold_result(first, second)(container))  # N: Revealed type is 'builtins.float*'
+    reveal_type(coalesce_result(first, second)(container))  # N: Revealed type is 'builtins.float*'
 
 
-- case: fold_ioresult_correct
+- case: coalesce_ioresult_correct
   disable_cache: true
   main: |
-    from returns.converters import fold_ioresult
+    from returns.converters import coalesce_ioresult
     from returns.io import IO, IOResult
 
     def first(arg: IO[int]) -> IO[float]:
@@ -27,13 +27,13 @@
         ...
 
     container: IOResult[int, str]
-    reveal_type(fold_ioresult(first, second)(container))  # N: Revealed type is 'returns.io.IO[builtins.float*]'
+    reveal_type(coalesce_ioresult(first, second)(container))  # N: Revealed type is 'returns.io.IO[builtins.float*]'
 
 
-- case: fold_ioresult_wrong
+- case: coalesce_ioresult_wrong
   disable_cache: true
   main: |
-    from returns.converters import fold_ioresult
+    from returns.converters import coalesce_ioresult
     from returns.io import IO, IOResult
 
     def first(arg: int) -> float:
@@ -43,17 +43,17 @@
         ...
 
     container: IOResult[int, str]
-    fold_ioresult(first, second)(container)
+    coalesce_ioresult(first, second)(container)
   out: |
     main:11: error: Argument 1 has incompatible type "Callable[[int], float]"; expected "Callable[[IO[<nothing>]], IO[<nothing>]]"
     main:11: error: Argument 1 has incompatible type "IOResult[int, str]"; expected "IOResult[<nothing>, <nothing>]"
     main:11: error: Argument 2 has incompatible type "Callable[[str], float]"; expected "Callable[[IO[<nothing>]], IO[<nothing>]]"
 
 
-- case: fold_maybe
+- case: coalesce_maybe
   disable_cache: true
   main: |
-    from returns.converters import fold_maybe
+    from returns.converters import coalesce_maybe
     from returns.maybe import Maybe
 
     def first(arg: int) -> float:
@@ -63,4 +63,4 @@
         ...
 
     container: Maybe[int]
-    reveal_type(fold_maybe(first, second)(container))  # N: Revealed type is 'builtins.float*'
+    reveal_type(coalesce_maybe(first, second)(container))  # N: Revealed type is 'builtins.float*'