Closes #148, closes #135, closes #145

Author: sobolevn

CHANGELOG.md

@@ -6,6 +6,20 @@ incremental in minor, bugfixes only are patches.
 See (0Ver)[https://0ver.org/].
 
 
+## 0.11.0 WIP
+
+### Features
+
+- Adds `tap` function
+- Now `pipe` allows to pipe 8 steps
+
+### Misc
+
+- Now all methods have doctests
+- Updates docs about `Success` and `_Success`, `Failure` and `_Failure`
+- Updates docs about `@pipeline`
+
+
 ## 0.10.0
 
 ### Features

README.md

@@ -14,8 +14,10 @@ Make your functions return something meaningful, typed, and safe!
 - Provides a bunch of primitives to write declarative business logic
 - Enforces better architecture
 - Fully typed with annotations and checked with `mypy`, [PEP561 compatible](https://www.python.org/dev/peps/pep-0561/)
+- Has a bunch of helpers for better composition
 - Pythonic and pleasant to write and to read (!)
 - Support functions and coroutines, framework agnostic
+- Easy to start: has lots of docs, tests, and tutorials
 
 
 ## Installation

docs/pages/container.rst

@@ -116,7 +116,7 @@ or we can fix the situation.
        S3 --> S5
        S5 --> S7
 
-       F2 -- Map Failure --> F4
+       F2 -- Alt --> F4
        F4 --> F6
        F6 --> F8
 

docs/pages/functions.rst

@@ -52,6 +52,23 @@ but how can we do it inversevely?
 That's it.
 
 
+tap
+---
+
+We need ``tap()`` function to easily compose values
+with functions that does not return.
+For example you sometimes need to ``print()`` values inside your :ref:`pipe`:
+
+.. code:: python
+
+  from returns.functions import tap
+
+  result = tap(print)(1)  # will print and return 1
+  # => prints 1
+  assert result == 1
+  # => True
+
+
 raise_exception
 ---------------
 

poetry.lock

@@ -46,11 +46,11 @@ typing-extensions = "^3.7"
 
 [tool.poetry.dev-dependencies]
 mypy = "^0.720"
-wemake-python-styleguide = "^0.12.3"
+wemake-python-styleguide = "^0.12.4"
 flake8-pytest = "^1.3"
 flake8-pytest-style = "^0.1.3"
 flake8-pyi = "^19.3"
-nitpick = "^0.20.0"
+nitpick = "^0.21.0"
 
 safety = "^1.8"
 

pyproject.toml

@@ -13,14 +13,42 @@
 def result_to_maybe(
     result_container: Result[_ValueType, _ErrorType],
 ) -> Maybe[_ValueType]:
-    """Converts ``Result`` container to ``Maybe`` container."""
+    """
+    Converts ``Result`` container to ``Maybe`` container.
+
+    .. code:: python
+
+      >>> from returns.maybe import Some, Nothing
+      >>> from returns.result import Failure, Success
+      >>> result_to_maybe(Success(1)) == Some(1)
+      True
+      >>> result_to_maybe(Failure(1)) == Nothing
+      True
+      >>> result_to_maybe(Success(None)) == Nothing
+      True
+
+    """
     return Maybe.new(result_container.value_or(None))
 
 
 def maybe_to_result(
     maybe_container: Maybe[_ValueType],
 ) -> Result[_ValueType, None]:
-    """Converts ``Maybe`` container to ``Result`` container."""
+    """
+    Converts ``Maybe`` container to ``Result`` container.
+
+    .. code:: python
+
+      >>> from returns.maybe import Some, Nothing
+      >>> from returns.result import Failure, Success
+      >>> maybe_to_result(Nothing) == Failure(None)
+      True
+      >>> maybe_to_result(Some(1)) == Success(1)
+      True
+      >>> maybe_to_result(Some(None)) == Failure(None)
+      True
+
+    """
     inner_value = maybe_container.value_or(None)
     if inner_value is not None:
         return Success(inner_value)
@@ -45,5 +73,20 @@ def join(
 
 
 def join(container):
-    """Joins two nested containers together."""
+    """
+    Joins two nested containers together.
+
+    .. code:: python
+
+      >>> from returns.maybe import Some
+      >>> from returns.result import Success
+      >>> from returns.io import IO
+      >>> join(IO(IO(1))) == IO(1)
+      True
+      >>> join(Some(Some(1))) == Some(1)
+      True
+      >>> join(Success(Success(1))) == Success(1)
+      True
+
+    """
     return container._inner_value  # noqa: WPS437

returns/converters.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-from typing import Callable, NoReturn, TypeVar
+from typing import Any, Callable, NoReturn, TypeVar
 
 from returns.generated.box import _box as box  # noqa: F401, WPS436
 
@@ -22,7 +22,6 @@ def compose(
 
     .. code:: python
 
-      >>> from returns.functions import compose
       >>> compose(float, int)('123.5')
       123
 
@@ -32,6 +31,32 @@ def compose(
     return lambda argument: second(first(argument))
 
 
+def tap(
+    function: Callable[[_FirstType], Any],
+) -> Callable[[_FirstType], _FirstType]:
+    """
+    Allows to apply some function and return an argument, instead of a result.
+
+    Is usefull for side-effects like ``print()``, ``logger.log``, etc.
+
+    .. code:: python
+
+      >>> tap(print)(1)
+      1
+      1
+      >>> tap(lambda _: 1)(2)
+      2
+
+    See also:
+        - https://github.com/dry-python/returns/issues/145
+
+    """
+    def decorator(argument_to_return: _FirstType) -> _FirstType:
+        function(argument_to_return)
+        return argument_to_return
+    return decorator
+
+
 def raise_exception(exception: Exception) -> NoReturn:
     """
     Helper function to raise exceptions as a function.
@@ -41,7 +66,6 @@ def raise_exception(exception: Exception) -> NoReturn:
 
     .. code:: python
 
-      >>> from returns.functions import raise_exception
       >>> from returns.result import Failure, Result
       >>> # Some operation result:
       >>> user: Result[int, ValueError] = Failure(ValueError('boom'))

returns/functions.py

@@ -10,6 +10,7 @@ _T5 = TypeVar('_T5')
 _T6 = TypeVar('_T6')
 _T7 = TypeVar('_T7')
 _T8 = TypeVar('_T8')
+_T9 = TypeVar('_T9')
 
 
 @overload
@@ -87,3 +88,18 @@ def _pipe(
     p8: Callable[[_T7], _T8],
 ) -> _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:
+    ...

returns/generated/pipe.pyi

@@ -46,6 +46,15 @@ def map(  # noqa: A003
         and returns a new IO object containing the result.
         'function' should accept a single "normal" (non-container) argument
         and return a non-container result.
+
+        .. code:: python
+
+          >>> def mappable(string: str) -> str:
+          ...      return string + 'b'
+          ...
+          >>> IO('a').map(mappable) == IO('ab')
+          True
+
         """
         return IO(function(self._inner_value))
 
@@ -57,6 +66,15 @@ def bind(
 
         'function' should accept a single "normal" (non-container) argument
         and return IO type object.
+
+        .. code:: python
+
+          >>> def bindable(string: str) -> IO[str]:
+          ...      return IO(string + 'b')
+          ...
+          >>> IO('a').bind(bindable) == IO('ab')
+          True
+
         """
         return function(self._inner_value)
 
@@ -75,7 +93,6 @@ def lift(
 
         .. code:: python
 
-          >>> from returns.io import IO
           >>> def example(argument: int) -> float:
           ...     return argument / 2  # not exactly IO action!
           ...