Introduces lift, pipe, and box

Author: sobolevn

.gitignore

@@ -195,3 +195,6 @@ com_crashlytics_export_strings.xml
 crashlytics.properties
 crashlytics-build.properties
 fabric.properties
+
+### Custom ###
+ex.py

CHANGELOG.md

@@ -1,16 +1,26 @@
 # Version history
 
-We follow Semantic Versions since the `0.1.0` release.
+We follow Semantic Versions since the `1.0.0` release.
+Versions before `1.0.0` are `0Ver`-based:
+incremental in minor, bugfixes only are patches.
+See (0Ver)[https://0ver.org/].
 
 
 ## 0.10.0 WIP
 
 ### Features
 
-- Now `bind` does not change the type of an error
-- Now `rescue` does not change the type of a value
-- Renames `map_failure` to `alt`
-- Adds `__hash__` magic methods to all containers
+- **Breaking**: `python>=3.7,<=3.7.2` are not supported anymore,
+  because of a bug inside `typing` module
+- **Breaking**: Now `bind` does not change the type of an error
+- **Breaking**: Now `rescue` does not change the type of a value
+- **Breaking**: Renames `map_failure` to `alt`
+- Adds `lift()` function with the ability
+  to lift function for direct container composition like:
+  `a -> Container[b]` to `Container[a] -> Container[b]`
+- Adds `lift_io()` function to lift `a -> a` to `IO[a] -> IO[a]`
+- Adds `pipe()` function to `pipeline.py`
+- Adds `__hash__()` magic methods to all containers
 
 ### Bugfixes
 
@@ -19,9 +29,10 @@ We follow Semantic Versions since the `0.1.0` release.
 
 ### Misc
 
+- Massive docs rewrite
 - Updates `mypy` version
 - Updates `wemake-python-styleguide` and introduces `nitpick`
-- Updates `pytest-plugin-mypy`
+- Updates `pytest-plugin-mypy`, all tests now use `yml`
 
 
 ## 0.9.0

README.md

@@ -107,20 +107,24 @@ just to catch the expected exceptions.
 
 Our code will become complex and unreadable with all this mess!
 
-### Pipeline example
+### Pipe example
 
 ```python
 import requests
-from returns.result import Result, pipeline, safe
+from returns.result import Result, safe
+from returns.pipeline import pipe
+from returns.functions import lift
 
 class FetchUserProfile(object):
     """Single responsibility callable object that fetches user profile."""
 
-    @pipeline
     def __call__(self, user_id: int) -> Result['UserProfile', Exception]:
-        """Fetches UserProfile dict from foreign API."""
-        response = self._make_request(user_id).unwrap()
-        return self._parse_json(response)
+        """Fetches `UserProfile` TypedDict from foreign API."""
+        return pipe(
+            user_id,
+            self._make_request,
+            lift(self._parse_json),
+        )
 
     @safe
     def _make_request(self, user_id: int) -> requests.Response:
@@ -145,20 +149,14 @@ decorator.
 It will return [Success[Response] or Failure[Exception]](https://returns.readthedocs.io/en/latest/pages/result.html).
 And will never throw this exception at us.
 
-When we will need raw value, we can use `.unwrap()` method to get it.
-If the result is `Failure[Exception]`
-we will actually raise an exception at this point.
-But it is safe to use `.unwrap()` inside
-[@pipeline](https://returns.readthedocs.io/en/latest/pages/functions.html#returns.functions.pipeline)
-functions.
-Because it will catch this exception
-and wrap it inside a new `Failure[Exception]`!
-
 And we can clearly see all result patterns
 that might happen in this particular case:
 - `Success[UserProfile]`
 - `Failure[Exception]`
 
+For more complex cases there's a [@pipeline](https://returns.readthedocs.io/en/latest/pages/functions.html#returns.functions.pipeline)
+decorator to help you with the composition.
+
 And we can work with each of them precisely.
 It is a good practice to create `Enum` classes or `Union` sum type
 with all the possible errors.
@@ -188,16 +186,21 @@ Let's refactor it to make our
 ```python
 import requests
 from returns.io import IO, impure
-from returns.result import Result, pipeline, safe
+from returns.result import Result, safe
+from returns.pipeline import pipe
+from returns.functions import lift, lift_io
 
 class FetchUserProfile(object):
     """Single responsibility callable object that fetches user profile."""
 
-    @pipeline
     def __call__(self, user_id: int) -> IO[Result['UserProfile', Exception]]:
-        """Fetches UserProfile dict from foreign API."""
-        return self._make_request(user_id).map(
-            lambda response: self._parse_json(response.unwrap())
+        """Fetches `UserProfile` TypedDict from foreign API."""
+        return pipe(
+            user_id,
+            self._make_request,
+            # lift: def (Result) -> Result
+            # lift_io: def (IO[Result]) -> IO[Result]
+            lift(box(self._parse_json), IO),
         )
 
     @impure
@@ -208,7 +211,7 @@ class FetchUserProfile(object):
         return response
 
     @safe
-    def _parse_json(self,response: requests.Response) -> 'UserProfile':
+    def _parse_json(self, response: requests.Response) -> 'UserProfile':
         return response.json()
 ```
 

poetry.lock

@@ -66,3 +66,4 @@ sphinx-typlog-theme = "^0.7.1"
 doc8 = "^0.8.0"
 m2r = "^0.2.1"
 tomlkit = "^0.5.5"
+flake8-pyi = "^19.3"

pyproject.toml

@@ -23,7 +23,7 @@ def maybe_to_result(
     """Converts ``Maybe`` container to ``Result`` container."""
     inner_value = maybe_container.value_or(None)
     if inner_value is not None:
-        return Success(inner_value)  # type: ignore
+        return Success(inner_value)
     return Failure(inner_value)
 
 

returns/converters.py

@@ -2,7 +2,9 @@
 
 from typing import Callable, NoReturn, TypeVar
 
-# Just aliases:
+from returns.generated.box import _box as box  # noqa: F401, WPS436
+
+# Aliases:
 _FirstType = TypeVar('_FirstType')
 _SecondType = TypeVar('_SecondType')
 _ThirdType = TypeVar('_ThirdType')
@@ -15,7 +17,7 @@ def compose(
     """
     Allows function composition.
 
-    Works as: ``second . first``
+    Works as: ``second . first`` or ``first() |> second()``.
     You can read it as "second after first".
 
     .. code:: python

returns/functions.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+
+"""
+This package contains code that was "generated" via metaprogramming.
+
+This happens, because python is not flexible enough to do most common
+tasks in typed functional programming.
+
+Policy:
+
+1. We store implementations in regular ``.py`` files.
+2. We store generated type annotations in ``.pyi`` files.
+3. We re-export these functions into regular modules as public values.
+
+Please, do not touch this code unless you know what you are doing.
+"""

returns/generated/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+
+def _box(function):
+    """
+    Boxes function's input parameter from a regular value to a container.
+
+    In other words, it modifies the function
+    signature from: ``a -> Container[b]`` to: ``Container[a] -> Container[b]``
+
+    This is how it should be used:
+
+    .. code:: python
+
+      >>> from returns.functions import box
+      >>> from returns.maybe import Maybe, Some
+      >>> def example(argument: int) -> Maybe[int]:
+      ...     return Some(argument + 1)
+      ...
+      >>> box(example)(Some(1)) == Some(2)
+      True
+
+    """
+    return lambda container: container.bind(function)

returns/generated/box.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, TypeVar, overload
+
+from returns.io import IO
+from returns.maybe import Maybe
+from returns.result import Result
+
+_ValueType = TypeVar('_ValueType')
+_ErrorType = TypeVar('_ErrorType')
+_NewValueType = TypeVar('_NewValueType')
+
+
+# Box:
+
+@overload
+def _box(
+    function: Callable[[_ValueType], Maybe[_NewValueType]],
+) -> Callable[[Maybe[_ValueType]], Maybe[_NewValueType]]:
+    ...
+
+
+@overload
+def _box(
+    function: Callable[[_ValueType], IO[_NewValueType]],
+) -> Callable[[IO[_ValueType]], IO[_NewValueType]]:
+    ...
+
+
+@overload
+def _box(
+    function: Callable[[_ValueType], Result[_NewValueType, _ErrorType]],
+) -> Callable[
+    [Result[_ValueType, _ErrorType]], Result[_NewValueType, _ErrorType],
+]:
+    ...

returns/generated/box.pyi

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+from functools import reduce
+
+from returns.functions import compose
+
+
+def _pipe(initial, *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.
+    Here's how it should be used:
+
+    .. code:: python
+
+       >>> from returns.pipeline import pipe
+
+       # => executes: str(float(int('1')))
+       >>> pipe('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 reduce(compose, functions)(initial)