Refs #224

Author: sobolevn

CHANGELOG.md

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

README.md

@@ -272,15 +272,16 @@ Our code will become complex and unreadable with all this mess!
 ```python
 import requests
 from returns.result import Result, safe
-from returns.pipeline import pipe
+from returns.pipeline import flow
 from returns.pointfree import bind
 
 def fetch_user_profile(user_id: int) -> Result['UserProfile', Exception]:
     """Fetches `UserProfile` TypedDict from foreign API."""
-    return pipe(
+    return flow(
+        user_id,
         _make_request,
         bind(_parse_json),
-    )(user_id)
+    )
 
 @safe
 def _make_request(user_id: int) -> requests.Response:
@@ -308,7 +309,7 @@ thanks to the
 decorator. It will return [Success[YourType] or Failure[Exception]](https://returns.readthedocs.io/en/latest/pages/result.html).
 And will never throw exception at us!
 
-We also use [pipe](https://returns.readthedocs.io/en/latest/pages/pipeline.html#pipe)
+We also use [flow](https://returns.readthedocs.io/en/latest/pages/pipeline.html#flow)
 and [bind](https://returns.readthedocs.io/en/latest/pages/pointfree.html#bind)
 functions for handy and declarative composition.
 
@@ -394,19 +395,20 @@ explicit!
 import requests
 from returns.io import IO, IOResult, impure_safe
 from returns.result import safe
-from returns.pipeline import pipe
+from returns.pipeline import flow
 from returns.pointfree import bind
 
 def fetch_user_profile(user_id: int) -> IOResult['UserProfile', Exception]:
     """Fetches `UserProfile` TypedDict from foreign API."""
-    return pipe(
+    return flow(
+        user_id,
         _make_request,
         # before: def (Response) -> UserProfile
         # after safe: def (Response) -> ResultE[UserProfile]
         # after bind: def (ResultE[Response]) -> ResultE[UserProfile]
         # after lift: def (IOResultE[Response]) -> IOResultE[UserProfile]
         IOResult.lift_result(bind(_parse_json)),
-    )(user_id)
+    )
 
 @impure_safe
 def _make_request(user_id: int) -> requests.Response:

docs/pages/pipeline.rst

@@ -9,55 +9,89 @@ composition easy, readable, pythonic, and useful.
 Let's start with the first one.
 
 
+flow
+----
+
+``flow`` allows to easily compose multiple functions together.
+It is useful when you already have an instance to compose functions with.
+
+Let's see an example.
+
+.. code:: python
+
+  >>> from returns.pipeline import flow
+  >>> assert flow(
+  ...     [1, 2, 3],
+  ...     lambda collection: max(collection),
+  ...     lambda max_number: -max_number,
+  ... ) == -3
+
+Use it when you need to compose a lot of functions together.
+
+And now let's get to know ``pipe``, it is very similar,
+but has different usage pattern.
+
+
 .. _pipe:
 
 pipe
 ----
 
 ``pipe`` is an easy way to compose functions together.
+It is useful when you don't have an instance to compose functions with yet.
+
 Let's see an example.
 
 .. code:: python
 
   >>> from returns.pipeline import pipe
 
-  >>> pipe(str, lambda x: x + 'b', str.upper)(1)
-  '1B'
+  >>> pipeline = pipe(str, lambda x: x + 'b', str.upper)
+  >>> assert pipeline(1) == '1B'
 
-There's also a way to compose containers together:
+It might be later used with multiple values:
 
 .. code:: python
 
-  from returns.pipeline import pipe
-  from returns.result import Result
-  from returns.functions import box
-
-  def regular_function(arg: int) -> float:
-      ...
+  >>> assert pipeline(2) == '2B'
 
-  def returns_container(arg: float) -> Result[complex, ValueError]:
-      ...
+It is also might be useful to compose containers together:
 
-  def also_returns_container(args: complex) -> Result[str, ValueError]:
-      ...
+.. code:: python
 
-  pipe(
-      regular_function,  # composes easily
-      returns_container,  # also composes easily, but returns a container...
-      # So we need to `box` the next function to allow it to consume
-      # the container from the previous step.
-      box(also_returns_container),
-  )(1)  # we provide the initial value itself as a argument to `pipe(...)`
-  # => Will return `Result[str, ValueError]` as declared in the last step
+  >>> from returns.pipeline import pipe
+  >>> from returns.result import Result, Success, Failure
+  >>> from returns.pointfree import bind
+
+  >>> def regular_function(arg: int) -> float:
+  ...     return float(arg)
+  ...
+
+  >>> def returns_container(arg: float) -> Result[str, ValueError]:
+  ...     if arg != 0:
+  ...          return Success(str(arg))
+  ...     return Failure(ValueError())
+  ...
+
+  >>> def also_returns_container(arg: str) -> Result[str, ValueError]:
+  ...     return Success(arg + '!')
+  ...
+
+  >>> transaction = pipe(
+  ...     regular_function,  # composes easily
+  ...     returns_container,  # also composes easily, but returns a container
+  ...     # So we need to `bind` the next function to allow it to consume
+  ...     # the container from the previous step.
+  ...     bind(also_returns_container),
+  ... )
+  >>> result = transaction(1)  # running the pipeline
+  >>> assert result == Success('1.0!')
 
 You might consider ``pipe()`` as :func:`returns.functions.compose` on steroids.
 The main difference is that ``compose`` takes strictly two arguments
 (or you might say that it has an arity of two),
 while ``pipe`` has infinite possible arguments.
 
-See also :func:`returns.io.IO.lift` which is also extremely
-helpful for ``IO`` composition.
-
 Limitations
 ~~~~~~~~~~~
 
@@ -69,6 +103,8 @@ But, composition with ``pipe`` is limited to two things:
 2. It is flexible. Sometimes you might need more power.
    Use ``@pipeline`` in this case!
 
+In contrast ``flow`` does not have these problems.
+
 
 .. _pipeline:
 

docs/pages/result.rst

@@ -40,7 +40,7 @@ Composition
 -----------
 
 Make sure to check out how to compose container with
-:ref:`pipe` and :ref:`@pipeline <pipeline>`!
+``flow``, :ref:`pipe` and :ref:`@pipeline <pipeline>`!
 Read more about them if you want to compose your containers easily.
 
 

returns/_generated/pipeline/__init__.py

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

returns/_generated/pipeline/flow.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+from functools import reduce
+
+from returns._generated.pipeline import pipe
+
+
+def _flow(instance, *functions):
+    """
+    Allows to compose a value and up to multiple functions that use this value.
+
+    All starts with the value itself.
+    Each next function uses the previous result as an input parameter.
+
+    This function is closely related
+    to :func:`pipe <returns._generated.pipeline.pipe._pipe>`
+    and solves several typing related issues.
+
+    Here's how it should be used:
+
+    .. code:: python
+
+       >>> from returns.pipeline import flow
+
+       # => executes: str(float(int('1')))
+       >>> assert flow('1', int, float, str) == '1.0'
+
+    See also:
+        - https://stackoverflow.com/a/41585450/4842742
+        - https://github.com/gcanti/fp-ts/blob/master/src/pipeable.ts
+
+    """
+    return pipe._pipe(*functions)(instance)

returns/_generated/pipeline/flow.pyi

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, TypeVar, overload
+
+_T1 = TypeVar('_T1')
+_T2 = TypeVar('_T2')
+_T3 = TypeVar('_T3')
+_T4 = TypeVar('_T4')
+_T5 = TypeVar('_T5')
+_T6 = TypeVar('_T6')
+_T7 = TypeVar('_T7')
+_T8 = TypeVar('_T8')
+_T9 = TypeVar('_T9')
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+) -> _T3:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+) -> _T4:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+) -> _T5:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+) -> _T6:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+    p6: Callable[[_T6], _T7],
+) -> _T7:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+    p6: Callable[[_T6], _T7],
+    p7: Callable[[_T7], _T8],
+) -> _T8:
+    ...
+
+
+@overload
+def _flow(
+    instance: _T1,
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+    p6: Callable[[_T6], _T7],
+    p7: Callable[[_T7], _T8],
+    p8: Callable[[_T8], _T9],
+) -> _T9:
+    ...

returns/_generated/pipe.py renamed to returns/_generated/pipeline/pipe.py

@@ -9,16 +9,15 @@ def _pipe(*functions):
     """
     Allows to compose a value and up to 7 functions that use this value.
 
-    Each next function uses the previos result as an input parameter.
+    Each next function uses the previous result as an input parameter.
     Here's how it should be used:
 
     .. code:: python
 
        >>> from returns.pipeline import pipe
 
        # => executes: str(float(int('1')))
-       >>> pipe(int, float, str)('1')
-       '1.0'
+       >>> assert pipe(int, float, str)('1') == '1.0'
 
     A friendly hint: do not start ``pipe`` definition with ``lambda`` function.
     ``mypy`` will complain: ``error: Cannot infer type argument 1 of "_pipe"``.
@@ -29,6 +28,7 @@ def _pipe(*functions):
 
     1. Use regular annotated functions
     2. Type the variable itself: ``user: Callable[[int], float] = pipe(...)``
+    3. Use :func:`flow <returns._generated.pipeline.flow._flow>` function
 
     See also:
         - https://stackoverflow.com/a/41585450/4842742