Closes #150

Author: sobolevn

CHANGELOG.md

@@ -10,6 +10,8 @@ See (0Ver)[https://0ver.org/].
 
 ### Features
 
+- **Breaking**: now `pipe()` does not require argument to be the first value,
+  instead it is required to use: `pipe(f1, f2, f3, f4)(value)`
 - Adds `tap` function
 - Now `pipe` allows to pipe 8 steps
 

docs/pages/pipeline.rst

@@ -21,7 +21,7 @@ Let's see an example.
 
   from returns.pipeline import pipe
 
-  pipe(1, str, lambda x: x + 'b', str.upper)
+  pipe(str, lambda x: x + 'b', str.upper)(1)
   # => Will be equal to: `1B`
 
 There's also a way to compose containers together:
@@ -42,15 +42,19 @@ There's also a way to compose containers together:
       ...
 
   pipe(
-      1,  # we provide the initial value itself as a first argument
       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
 
+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.
 

returns/generated/pipe.py

@@ -5,7 +5,7 @@
 from returns.functions import compose
 
 
-def _pipe(initial, *functions):
+def _pipe(*functions):
     """
     Allows to compose a value and up to 7 functions that use this value.
 
@@ -17,12 +17,14 @@ def _pipe(initial, *functions):
        >>> from returns.pipeline import pipe
 
        # => executes: str(float(int('1')))
-       >>> pipe('1', int, float, str)
+       >>> pipe(int, float, str)('1')
        '1.0'
 
     See also:
         - https://stackoverflow.com/a/41585450/4842742
         - https://github.com/gcanti/fp-ts/blob/master/src/pipeable.ts
 
     """
-    return reduce(compose, functions)(initial)
+    def decorator(initial):
+        return reduce(compose, functions)(initial)
+    return decorator

returns/generated/pipe.pyi

@@ -15,91 +15,76 @@ _T9 = TypeVar('_T9')
 
 @overload
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-) -> _T2:
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+) -> Callable[[_T1], _T3]:
     ...
 
 
 @overload
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-) -> _T3:
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+) -> Callable[[_T1], _T4]:
     ...
 
 
 @overload
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-) -> _T4:
-    ...
-
-
-@overload
-def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-    p5: Callable[[_T4], _T5],
-) -> _T5:
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+) -> Callable[[_T1], _T5]:
     ...
 
 
 @overload  # noqa: WPS211
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-    p5: Callable[[_T4], _T5],
-    p6: Callable[[_T5], _T6],
-) -> _T6:
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+) -> Callable[[_T1], _T6]:
     ...
 
 
 @overload  # noqa: WPS211
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-    p5: Callable[[_T4], _T5],
-    p6: Callable[[_T5], _T6],
-    p7: Callable[[_T6], _T7],
-) -> _T7:
+    p1: Callable[[_T1], _T2],
+    p2: Callable[[_T2], _T3],
+    p3: Callable[[_T3], _T4],
+    p4: Callable[[_T4], _T5],
+    p5: Callable[[_T5], _T6],
+    p6: Callable[[_T6], _T7],
+) -> Callable[[_T1], _T7]:
     ...
 
 
 @overload  # noqa: WPS211
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-    p5: Callable[[_T4], _T5],
-    p6: Callable[[_T5], _T6],
-    p7: Callable[[_T6], _T7],
-    p8: Callable[[_T7], _T8],
-) -> _T8:
+    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],
+) -> Callable[[_T1], _T8]:
     ...
 
 
 @overload  # noqa: WPS211
 def _pipe(
-    p1: _T1,
-    p2: Callable[[_T1], _T2],
-    p3: Callable[[_T2], _T3],
-    p4: Callable[[_T3], _T4],
-    p5: Callable[[_T4], _T5],
-    p6: Callable[[_T5], _T6],
-    p7: Callable[[_T6], _T7],
-    p8: Callable[[_T7], _T8],
-    p9: Callable[[_T8], _T9],
-) -> _T9:
+    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],
+) -> Callable[[_T1], _T9]:
     ...

tests/test_pipeline/test_pipe.py

@@ -16,10 +16,9 @@ class _UserProfile(object):
     def __call__(self, user_id: int) -> IO[Result[float, Exception]]:
         """Fetches `UserProfile` TypedDict from foreign API."""
         return pipe(
-            user_id,
             self._make_request,
             IO.lift(box(self._parse_json)),
-        )
+        )(user_id)
 
     @impure
     @safe

typesafety/test_pipeline/test_pipe.yml

@@ -3,4 +3,9 @@
   main: |
     from returns.pipeline import pipe
 
-    reveal_type(pipe('1.0', float, int, bool))  # N: Revealed type is 'builtins.bool*'
+    def convert(arg: str) -> float:
+        return float(arg)
+
+    predefined = pipe(convert, int, bool)
+    reveal_type(predefined)  # N: Revealed type is 'def (builtins.str*) -> builtins.bool*'
+    reveal_type(predefined('1.0'))  # N: Revealed type is 'builtins.bool*'