Adds squash_context, closes #234

Author: sobolevn

CHANGELOG.md

@@ -13,6 +13,8 @@ See [0Ver](https://0ver.org/).
 - **Breaking**: renames `join` to `flatten`, sorry!
 - **Breaking**: renames `box` to `bind` and moves it to `returns.pointfree`
 - **Breaking**: removes `Maybe.rescue` and `Maybe.fix` methods
+- **Breaking**: renames `io_squash` to `squash_io`
+  and moves it to `returns.converters`
 
 - Adds `rescue` pointfree function
 - Adds `ResultE` alias for `Result[..., Exception]`
@@ -50,6 +52,7 @@ See [0Ver](https://0ver.org/).
   methods for all `Result` realted classes
 - Adds `flow` function, which is similar to `pipe`
 - Adds `swap` coverter for `Result` and `IOResult`
+- Adds `squash_context` function to squash `RequiresContext` similar to `IO`
 
 
 ### Bugfixes

docs/pages/converters.rst

@@ -110,10 +110,59 @@ one for successful case, one for failing case.
   ...     return 0.0
   ...
 
-  >>> coalesce_result(handle_success, handle_failure)(Success(1))
-  0.5
-  >>> coalesce_result(handle_success, handle_failure)(Failure(1))
-  0.0
+  >>> assert coalesce_result(handle_success, handle_failure)(Success(1)) == 0.5
+  >>> assert coalesce_result(handle_success, handle_failure)(Failure(1)) == 0.0
+
+
+squash
+------
+
+squash_io
+~~~~~~~~~
+
+:func:`returns.converters.squash_io` function
+allows to squash several ``IO`` containers together.
+
+That's how it works:
+
+.. code:: python
+
+  >>> from returns.io import IO
+  >>> from returns.converters import squash_io
+
+  >>> assert squash_io(IO('first'), IO('second')) == IO(('first', 'second'))
+  >>> # => revealed type of this instance is `IO[Tuple[str, str]]`
+
+It might be helpful if you want
+to work with mutliple ``IO`` instances at the same time.
+
+This approach saves you you from multiple nested ``IO.map`` calls.
+You can work with tuples instead like so:
+
+.. code:: python
+
+  >>> plus = squash_io(IO(1), IO('a')).map(lambda args: args[0] + len(args[1]))
+  >>> assert plus == IO(3)
+
+We support up to 9 typed parameters to this function.
+
+squash_context
+~~~~~~~~~~~~~~
+
+:func:`returns.converters.squash_context` is similar to ``squash_io``,
+but works with ``RequiresContext`` container.
+
+.. code:: python
+
+  >>> from returns.context import RequiresContext
+  >>> from returns.converters import squash_context
+
+  >>> assert squash_context(
+  ...     RequiresContext.from_value(1),
+  ...     RequiresContext.from_value('a'),
+  ... )(...) == RequiresContext.from_value((1, 'a'))(...)
+  >>> # revealed type is: RequiresContext[Any, Tuple[int, str]]
+
 
 
 API Reference
@@ -123,11 +172,12 @@ API Reference
 
 .. autofunction:: returns.converters.flatten
 
-.. autofunction:: returns.converters.coalesce_maybe
-
-.. autofunction:: returns.converters.coalesce_result
+.. autofunction:: returns.converters.squash_io
 
-.. autofunction:: returns.converters.coalesce_ioresult
+.. autofunction:: returns.converters.squash_context
 
 .. automodule:: returns.converters
    :members:
+
+.. autofunction:: returns.converters.coalesce_maybe
+

docs/pages/io.rst

@@ -320,33 +320,7 @@ Use for impure operations that might fail.
 Helpers
 -------
 
-io_squash
-~~~~~~~~~
-
-This function allows to squash several ``IO`` containers together.
-
-That's how it works:
-
-.. code:: python
-
-  >>> from returns.io import IO, io_squash
-
-  >>> assert io_squash(IO('first'), IO('second')) == IO(('first', 'second'))
-  >>> # => revealed type of this instance is `IO[Tuple[str, str]]`
-
-It might be helpful if you want
-to work with mutliple ``IO`` instances at the same time.
-
-This approach saves you you from multiple nested ``IO.map`` calls.
-You can work with tuples instead like so:
-
-.. code:: python
-
-  >>> plus = io_squash(IO(1), IO(2)).map(lambda args: args[0] + args[1])
-  >>> assert plus == IO(3)
-
-We support up to 9 typed parameters to this function.
-
+Don't forget to check out :ref:`converters`.
 
 .. _unsafe_perform_io:
 

returns/_generated/converters/coalesce.py

@@ -53,7 +53,7 @@
 _FirstType = TypeVar('_FirstType')
 
 
-def _fold(success_handler, failure_handler):
+def _coalesce(success_handler, failure_handler):
     """
     We need this function, because we cannot use a single typed function.
 
@@ -72,7 +72,7 @@ def decorator(container):
         Callable[[_ErrorType], _FirstType],
     ],
     Callable[[Result[_ValueType, _ErrorType]], _FirstType],
-] = _fold
+] = _coalesce
 _coalesce_result.__doc__ = __doc__
 
 _coalesce_ioresult: Callable[
@@ -81,7 +81,7 @@ def decorator(container):
         Callable[[IO[_ErrorType]], IO[_FirstType]],
     ],
     Callable[[IOResult[_ValueType, _ErrorType]], IO[_FirstType]],
-] = _fold
+] = _coalesce
 _coalesce_ioresult.__doc__ = __doc__
 
 _coalesce_maybe: Callable[
@@ -90,5 +90,5 @@ def decorator(container):
         Callable[[None], _FirstType],
     ],
     Callable[[Maybe[_ValueType]], _FirstType],
-] = _fold
+] = _coalesce
 _coalesce_maybe.__doc__ = __doc__

returns/_generated/converters/squash.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+from returns.context import RequiresContext
+from returns.io import IO
+
+
+def _squash_io(*args):
+    """
+    Unwraps ``IO`` values, merges them into tuple, and wraps back.
+
+    .. code:: python
+
+        >>> from returns.io import IO
+        >>> from returns.converters import squash_io
+        >>> assert squash_io(IO('a'), IO('b')) == IO(('a', 'b'))
+
+    Why this only exists for ``IO`` and ``RequiresContext``?
+    Because these types represent real values, that do not possibly fail.
+
+    How would you, for example, squash two ``Result`` values?
+    ``Success(1)`` and ``Failure(2)`` would not give you a tuple when squashed.
+    """
+    return IO(tuple(
+        container._inner_value  # noqa:  WPS437
+        for container in args
+    ))
+
+
+def _squash_context(*args):
+    """
+    Unwraps ``RequiresContext`` values, merges them into tuple, and wraps back.
+
+    .. code:: python
+
+        >>> from returns.context import RequiresContext
+        >>> from returns.converters import squash_context
+        >>> assert squash_context(
+        ...     RequiresContext.from_value(1),
+        ...     RequiresContext.from_value('a'),
+        ...     RequiresContext.from_value(True),
+        ... )(...) == RequiresContext.from_value((1, 'a', True))(...)
+
+    See :func:`returns.converters.squash_io` for more docs.
+    """
+    return RequiresContext(lambda deps: tuple(
+        func(deps)
+        for func in args
+    ))