Closes #221, closes #206

Author: sobolevn

.travis.yml

@@ -1,10 +1,9 @@
 language: python
 dist: xenial
 
-matrix:
-  include:
-    - python: 3.6
-    - python: 3.7.3
+python:
+  - 3.6
+  - 3.7.6
 
 
 before_install:

CHANGELOG.md

@@ -6,11 +6,15 @@ incremental in minor, bugfixes only are patches.
 See (0Ver)[https://0ver.org/].
 
 
-## 0.13.0
+## 0.13.0 WIP
 
 ### Features
 
-- Adds `io_squash` to squash several `IO` containers into one container with a tuple inside, currently works with `9` containers max at a time
+- **Breaking**: now `@pipeline` requires a container type when created:
+  `@pipeline(Result)` or `@pipeline(Maybe)`
+- Adds `io_squash` to squash several `IO` containers into one container
+  with a tuple inside, currently works with `9` containers max at a time
+- Adds `untap` function which does convert return type to `None`
 
 ### Bugfixes
 

docs/pages/functions.rst

@@ -81,6 +81,10 @@ For example you sometimes need to ``print()`` values inside your :ref:`pipe`:
   assert result == 1
   # => True
 
+You can also use ``untap`` function to turn any function
+return type to ``None``.
+This is also sometimes helpful for a typed function composition.
+
 
 raise_exception
 ---------------
@@ -94,7 +98,7 @@ We allow you to do that with ease!
 
   from returns.functions import raise_exception
 
-  @pipeline
+  @pipeline(Result)
   def create_account_and_user(username: str) -> ...:
       """
       Creates new Account-User pair.

docs/pages/maybe.rst

@@ -1,3 +1,5 @@
+.. _maybe:
+
 Maybe
 =====
 

docs/pages/pipeline.rst

@@ -75,10 +75,18 @@ But, composition with ``pipe`` is limited to two things:
 pipeline
 --------
 
-What is a ``pipeline``?
+What is a ``@pipeline``?
 It is a more user-friendly syntax to work with containers
 that support both async and regular functions.
 
+``@pipeline`` decorator allows you to ``.unwrap`` container values
+from containers and work with them
+as with regular values (which they are in this context).
+
+It is something like ``do-notation`` if you wish.
+
+Works with both :ref:`Maybe <maybe>` and :ref:`Result <result>` container.
+
 Consider this task.
 We were asked to create a method
 that will connect together a simple pipeline of three steps:
@@ -168,7 +176,7 @@ Let's see an example.
 
 .. code:: python
 
-  @pipeline
+  @pipeline(Result)
   def create_account_and_user(
       username: str,
       email: str,
@@ -223,7 +231,7 @@ And the returning value will be different.
   from returns.result import Result
   from returns.pipeline import pipeline
 
-  @pipeline
+  @pipeline(Result)
   def example() -> Result[int, str]:
       other: Result[int, Exception]
       new_value = other.unwrap() + 1  # hidden boom!

docs/pages/result.rst

@@ -1,3 +1,5 @@
+.. _result:
+
 Result
 ======
 

returns/functions.py

@@ -93,6 +93,35 @@ def decorator(argument_to_return: _FirstType) -> _FirstType:
     return decorator
 
 
+def untap(
+    function: Callable[[_FirstType], Any],
+) -> Callable[[_FirstType], None]:
+    """
+    Allows to apply some function and always return ``None`` as a result.
+
+    Is usefull for composing functions that do some side effects
+    and return some nosense.
+
+    Is the kind of a reverse of the ``tap`` function.
+
+    .. code:: python
+
+      >>> def strange_log(arg: int) -> int:
+      ...     print(arg)
+      ...     return arg
+      >>> untap(strange_log)(2)
+      2
+      >>> untap(tap(lambda _: 1))(2)
+
+    See also:
+        - https://github.com/dry-python/returns/issues/145
+
+    """
+    def decorator(argument_to_return: _FirstType) -> None:
+        function(argument_to_return)
+    return decorator
+
+
 def raise_exception(exception: Exception) -> NoReturn:
     """
     Helper function to raise exceptions as a function.

returns/pipeline.py

@@ -2,7 +2,9 @@
 
 from functools import wraps
 from inspect import iscoroutinefunction
-from typing import Callable, Coroutine, TypeVar, Union, overload
+from typing import Callable, Coroutine, Type, TypeVar, Union, overload
+
+from typing_extensions import Protocol
 
 from returns._generated.pipe import _pipe as pipe  # noqa: F401, WPS436
 from returns.maybe import Maybe
@@ -17,13 +19,22 @@
 _SecondType = TypeVar('_SecondType')
 
 # Hacks for functions:
-_ReturnsResultType = TypeVar(
-    '_ReturnsResultType',
-    bound=Callable[..., _Unwrapable],
+_ReturnResultType = TypeVar(
+    '_ReturnResultType',
+    bound=Callable[..., Result],
 )
-_AsyncReturnsResultType = TypeVar(
-    '_AsyncReturnsResultType',
-    bound=Callable[..., Coroutine[_FirstType, _SecondType, _Unwrapable]],
+_AsyncReturnResultType = TypeVar(
+    '_AsyncReturnResultType',
+    bound=Callable[..., Coroutine[_FirstType, _SecondType, Result]],
+)
+
+_ReturnMaybeType = TypeVar(
+    '_ReturnMaybeType',
+    bound=Callable[..., Maybe],
+)
+_AsyncReturnMaybeType = TypeVar(
+    '_AsyncReturnMaybeType',
+    bound=Callable[..., Coroutine[_FirstType, _SecondType, Maybe]],
 )
 
 
@@ -56,36 +67,83 @@ def is_successful(container: _Unwrapable) -> bool:
         return True
 
 
+class _PipelineResultProtocol(Protocol):
+    @overload
+    def __call__(self, function: _ReturnResultType) -> _ReturnResultType:
+        """Sync pipeline case for ``Result`` container."""
+
+    @overload  # noqa: F811
+    def __call__(
+        self, function: _AsyncReturnResultType,
+    ) -> _AsyncReturnResultType:
+        """Async pipeline case for ``Result`` container."""
+
+
+class _PipelineMaybeProtocol(Protocol):
+    @overload
+    def __call__(self, function: _ReturnMaybeType) -> _ReturnMaybeType:
+        """Sync pipeline case for ``Maybe`` container."""
+
+    @overload  # noqa: F811
+    def __call__(
+        self, function: _AsyncReturnMaybeType,
+    ) -> _AsyncReturnMaybeType:
+        """Async pipeline case for ``Maybe`` container."""
+
+
 @overload
 def pipeline(
-    function: _AsyncReturnsResultType,
-) -> _AsyncReturnsResultType:
-    """Case for async functions."""
+    container_type: Type[Result],
+) -> _PipelineResultProtocol:
+    """Pipeline case for ``Result`` container."""
 
 
 @overload
-def pipeline(function: _ReturnsResultType) -> _ReturnsResultType:
-    """Case for regular functions."""
+def pipeline(
+    container_type: Type[Maybe],
+) -> _PipelineMaybeProtocol:
+    """Pipeline case for ``Maybe`` container."""
 
 
-def pipeline(function):  # noqa: C901
+def pipeline(container_type):  # noqa: C901, WPS212
     """
     Decorator to enable ``do-notation`` context.
 
     Should be used for series of computations that rely on ``.unwrap`` method.
-
     Supports both async and regular functions.
+
+    Works with both ``Maybe`` and ``Result`` containers.
+
+    Example:
+    .. code:: python
+
+        >>> from typing import Optional
+        >>> @pipeline(Maybe)
+        ... def test(one: Optional[int], two: Optional[int]) -> Maybe[int]:
+        ...      first = Maybe.new(one).unwrap()
+        ...      second = Maybe.new(two).unwrap()
+        ...      return Maybe.new(first + second)
+        ...
+        >>> str(test(1, 2))
+        '<Some: 3>'
+        >>> str(test(2, None))
+        '<Nothing>'
+
+    Make sure to supply the correct container type when creating a pipeline.
+
     """
-    if iscoroutinefunction(function):
-        async def decorator(*args, **kwargs):  # noqa: WPS430
-            try:
-                return await function(*args, **kwargs)
-            except UnwrapFailedError as exc:
-                return exc.halted_container
-    else:
-        def decorator(*args, **kwargs):  # noqa: WPS430
-            try:
-                return function(*args, **kwargs)
-            except UnwrapFailedError as exc:
-                return exc.halted_container
-    return wraps(function)(decorator)
+    def factory(function):
+        if iscoroutinefunction(function):
+            async def decorator(*args, **kwargs):  # noqa: WPS430
+                try:
+                    return await function(*args, **kwargs)
+                except UnwrapFailedError as exc:
+                    return exc.halted_container
+        else:
+            def decorator(*args, **kwargs):  # noqa: WPS430
+                try:
+                    return function(*args, **kwargs)
+                except UnwrapFailedError as exc:
+                    return exc.halted_container
+        return wraps(function)(decorator)
+    return factory

tests/test_pipeline/test_maybe_pipeline.py

@@ -6,13 +6,13 @@
 from returns.pipeline import pipeline
 
 
-@pipeline
+@pipeline(Maybe)
 def _maybe_pipeline(number: int) -> Maybe[int]:
     first: int = Some(number).unwrap() if number else Nothing.unwrap()
     return Some(first + number)
 
 
-@pipeline
+@pipeline(Maybe)
 async def _async_maybe_pipeline(number: int) -> Maybe[int]:
     first: int = Some(number).unwrap() if number else Nothing.unwrap()
     return Some(first + number)

tests/test_pipeline/test_result_pipeline.py

@@ -16,13 +16,13 @@ def _sum(first: int, second: float) -> float:
     return first + second
 
 
-@pipeline
+@pipeline(Result)
 def _result_pipeline(number: int) -> Result[float, Exception]:
     divided = _divide(number).unwrap()
     return _sum(number, divided)
 
 
-@pipeline
+@pipeline(Result)
 async def _result_async_pipeline(number: int) -> Result[float, Exception]:
     divided = _divide(number).unwrap()
     return _sum(number, divided)

typesafety/test_functions/test_tap.yml

@@ -7,3 +7,15 @@
         return float(num)
 
     reveal_type(tap(first))  # N: Revealed type is 'def (builtins.int*) -> builtins.int*'
+
+
+- case: untap_single_function
+  disable_cache: true
+  main: |
+    from returns.functions import untap
+
+    def first(num: int) -> float:
+        return float(num)
+
+    reveal_type(untap(first))  # N: Revealed type is 'def (builtins.int*)'
+    reveal_type(untap(first)(1))  # N: Revealed type is 'None'

typesafety/test_pipeline/test_maybe_pipeline.yml

@@ -0,0 +1,42 @@
+- case: maybe_pipeline
+  disable_cache: true
+  main: |
+    from returns.pipeline import pipeline
+    from returns.maybe import Maybe
+
+    @pipeline(Maybe)
+    def returns_maybe(arg: str) -> Maybe[str]:
+        ...
+
+    reveal_type(returns_maybe("a"))  # N: Revealed type is 'returns.maybe.Maybe[builtins.str]'
+
+
+- case: maybe_async_pipeline
+  disable_cache: true
+  main: |
+    from returns.pipeline import pipeline
+    from returns.maybe import Maybe
+
+    @pipeline(Maybe)
+    async def returns_maybe(arg: str) -> Maybe[str]:
+        ...
+
+    reveal_type(returns_maybe("a"))  # N: Revealed type is 'typing.Coroutine[Any, Any, returns.maybe.Maybe[builtins.str]]'
+
+
+- case: maybe_wrong_pipeline
+  disable_cache: true
+  main: |
+    from returns.pipeline import pipeline
+    from returns.maybe import Maybe
+    from returns.result import Result
+
+    @pipeline(Result)
+    def returns_maybe(arg: str) -> Maybe[int]:
+        ...
+
+    reveal_type(returns_maybe("a"))
+
+  out: |
+    main:5: error: Value of type variable "_ReturnResultType" of "__call__" of "_PipelineResultProtocol" cannot be "Callable[[str], Maybe[int]]"
+    main:9: note: Revealed type is 'returns.maybe.Maybe[builtins.int]'