Version 0.10 pre-release

Author: sobolevn

CHANGELOG.md

@@ -15,10 +15,10 @@ See (0Ver)[https://0ver.org/].
 - **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:
+- Adds `box()` function with the ability
+  to box 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 `IO.lift()` function to lift `a -> a` to `IO[a] -> IO[a]`
 - Adds `pipe()` function to `pipeline.py`
 - Adds `__hash__()` magic methods to all containers
 

README.md

@@ -42,9 +42,41 @@ Make sure you know how to get started, [check out our docs](https://returns.read
 
 ## Contents
 
+- [Maybe container](#maybe-container) that allows you to write `None`-free code
 - [Result container](#result-container) that let's you to get rid of exceptions
 - [IO marker](#io-marker) that marks all impure operations and structures them
-- [Maybe container](#maybe-container) that allows you to write `None`-free code
+
+
+## Maybe container
+
+`None` is called the [worst mistake in the history of Computer Science](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/).
+
+So, what can we do to check for `None` in our programs?
+You can use `Optional` and write a lot of `if some is not None:` conditions.
+But, having them here and there makes your code unreadable.
+
+Or you can use
+[Maybe](https://returns.readthedocs.io/en/latest/pages/maybe.html) container!
+It consists of `Some` and `Nothing` types,
+representing existing state and empty (instead of `None`) state respectively.
+
+```python
+from typing import Optional
+from returns.maybe import Maybe, maybe
+
+@maybe  # decorator to convert existing Optional[int] to Maybe[int]
+def bad_function() -> Optional[int]:
+    ...
+
+maybe_result: Maybe[float] = bad_function().map(
+    lambda number: number / 2,
+)
+# => Maybe will return Some[float] only if there's a non-None value
+#    Otherwise, will return Nothing
+```
+
+You can be sure that `.map()` method won't be called for `Nothing`.
+Forget about `None`-related errors forever!
 
 
 ## Result container
@@ -113,7 +145,7 @@ Our code will become complex and unreadable with all this mess!
 import requests
 from returns.result import Result, safe
 from returns.pipeline import pipe
-from returns.functions import lift
+from returns.functions import box
 
 class FetchUserProfile(object):
     """Single responsibility callable object that fetches user profile."""
@@ -123,7 +155,7 @@ class FetchUserProfile(object):
         return pipe(
             user_id,
             self._make_request,
-            lift(self._parse_json),
+            box(self._parse_json),
         )
 
     @safe
@@ -137,13 +169,19 @@ class FetchUserProfile(object):
         return response.json()
 ```
 
-Now we have a clean and a safe way to express our business need.
+Now we have a clean and a safe and declarative way
+to express our business need.
 We start from making a request, that might fail at any moment.
+Then parsing the response if the request was successful.
+And then return the result.
+It all happens smoothly due to [pipe](https://returns.readthedocs.io/en/latest/pages/pipeline.html#pipe) function.
+
+We also use [box](https://returns.readthedocs.io/en/latest/pages/functions.html#box) for handy composition.
 
 Now, instead of returning a regular value
 it returns a wrapped value inside a special container
 thanks to the
-[@safe](https://returns.readthedocs.io/en/latest/pages/functions.html#returns.functions.safe)
+[@safe](https://returns.readthedocs.io/en/latest/pages/result.html#safe)
 decorator.
 
 It will return [Success[Response] or Failure[Exception]](https://returns.readthedocs.io/en/latest/pages/result.html).
@@ -188,7 +226,7 @@ import requests
 from returns.io import IO, impure
 from returns.result import Result, safe
 from returns.pipeline import pipe
-from returns.functions import lift, lift_io
+from returns.functions import box
 
 class FetchUserProfile(object):
     """Single responsibility callable object that fetches user profile."""
@@ -198,9 +236,9 @@ class FetchUserProfile(object):
         return pipe(
             user_id,
             self._make_request,
-            # lift: def (Result) -> Result
-            # lift_io: def (IO[Result]) -> IO[Result]
-            lift(box(self._parse_json), IO),
+            # after box: def (Result) -> Result
+            # after IO.lift: def (IO[Result]) -> IO[Result]
+            IO.lift(box(self._parse_json)),
         )
 
     @impure
@@ -223,39 +261,6 @@ that it does `IO` and might fail.
 So, we act accordingly!
 
 
-## Maybe container
-
-`None` is called the [worst mistake in the history of Computer Science](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/).
-
-So, what can we do?
-You can use `Optional` and write a lot of `if some is not None` conditions.
-But, having them here and there makes your code unreadable.
-
-Or you can use
-[Maybe](https://returns.readthedocs.io/en/latest/pages/maybe.html) container!
-It consists of `Some` and `Nothing` types,
-representing existing state and empty (instead of `None`) state respectively.
-
-```python
-from typing import Optional
-from returns.maybe import Maybe, maybe
-
-@maybe
-def bad_function() -> Optional[int]:
-    ...
-
-maybe_result: Maybe[float] = bad_function().map(
-    lambda number: number / 2,
-)
-# => Maybe will return Some[float] only if there's a non-None value
-#    Otherwise, will return Nothing
-```
-
-It follows the same composition rules as the `Result` type.
-You can be sure that `.map()` method won't be called for `Nothing`.
-Forget about `None`-related errors forever!
-
-
 ## More!
 
 Want more? [Go to the docs!](https://returns.readthedocs.io)

docs/conf.py

@@ -74,6 +74,10 @@ def _get_project_meta():
     'exclude-members': '__dict__,__weakref__',
 }
 
+# Set `typing.TYPE_CHECKING` to `True`:
+# https://pypi.org/project/sphinx-autodoc-typehints/
+set_type_checking_flag = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/index.rst

@@ -17,10 +17,10 @@ Contents
   :caption: Userguide
 
   pages/container.rst
-  pages/result.rst
   pages/maybe.rst
   pages/io.rst
-  pages/unsafe.rst
+  pages/result.rst
+  pages/pipeline.rst
   pages/functions.rst
 
 .. toctree::
@@ -31,7 +31,7 @@ Contents
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/pages/container.rst

@@ -9,9 +9,9 @@ while maintaining the execution context.
 
 List of supported containers:
 
+- :class:`Maybe <returns.maybe.Maybe>` to handle ``None`` cases
 - :class:`IO <returns.io.IO>` to mark explicit ``IO`` actions
 - :class:`Result <returns.result.Result>` to handle possible exceptions
-- :class:`Maybe <returns.maybe.Maybe>` to handle ``None`` cases
 
 We will show you container's simple API of one attribute
 and several simple methods.

docs/pages/functions.rst

@@ -23,6 +23,35 @@ functions with one argument and one return to be composed.
 Only works with regular functions (not async).
 
 
+box
+---
+
+Without ``box()`` it would be very hard to declaratively compose two entities:
+
+1. Existings container
+2. Existing functions that accepts a regular value and returns a container
+
+We can compose these entities with ``.bind`` when calling it directly,
+but how can we do it inversevely?
+
+.. code:: python
+
+  from returns.functions import box
+  from returns.maybe import Maybe
+
+  def bindable(arg: int) -> Maybe[str]:
+      ...
+
+  container: Maybe[int]
+  # We now have two way of composining these entities.
+  # 1. Via ``.bind``:
+  container.bind(bindable)  # works!
+  # 2. Or via ``box``, the same but in the inverse way:
+  box(bindable)(container)
+
+That's it.
+
+
 raise_exception
 ---------------
 
@@ -65,3 +94,5 @@ API Reference
 
 .. automodule:: returns.functions
    :members:
+
+.. autofunction:: returns.functions.box

docs/pages/io.rst

@@ -140,6 +140,27 @@ We can track it, we can fight it, we can design it better.
 By saying that, it is assumed that
 you have a functional core and imperative shell.
 
+Lifting
+~~~~~~~
+
+You can also lift regular function into one
+that works with ``IO`` on both ends. It really helps you with the composition!
+
+.. code:: python
+
+  def regular_function(arg: int) -> float:
+      return arg / 2  # not an `IO` operation
+
+  container: IO[int]
+  # When we need to compose `regular_function` with `IO`,
+  # we have two ways of doing it:
+  container.map(regular_function)
+  # or, it is the same as:
+  IO.lift(regular_function)(container)
+
+The second variant is useful when using :func:`returns.pipeline.pipe`
+and other different declarative tools.
+
 
 impure
 ------
@@ -173,6 +194,42 @@ if :ref:`decorator_plugin <type-safety>` is used.
 This happens due to `mypy issue <https://github.com/python/mypy/issues/3157>`_.
 
 
+unsafe_perform_io
+-----------------
+
+Sometimes you really need to get the raw value from ``IO`` container.
+For example:
+
+.. code:: python
+
+  def index_view(request, user_id):
+      user: IO[User] = get_user(user_id)
+      return render('index.html', { user: user })  # ???
+
+In this case your web-framework will not render your user correctly.
+Since it does not expect it to be wrapped inside ``IO`` containers.
+And we obviously cannot ``map`` or ``bind`` this function.
+
+What to do? Use :func:`unsafe_perform_io <returns.unsafe.unsafe_perform_io>`:
+
+.. code::
+
+  from returns.unsafe import unsafe_perform_io
+
+  def index_view(request, user_id):
+      user: IO[User] = get_user(user_id)
+      return render('index.html', { user: unsafe_perform_io(user) })  # Ok
+
+We need it as an escape and compatibility mechanism for our imperative shell.
+
+It is recommended
+to use `import-linter <https://github.com/seddonym/import-linter>`_
+to restrict imports from ``returns.unsafe`` expect the top-level modules.
+
+Inspired by Haskell's
+`unsafePerformIO <https://hackage.haskell.org/package/base-4.12.0.0/docs/System-IO-Unsafe.html#v:unsafePerformIO>`_
+
+
 FAQ
 ---
 
@@ -238,3 +295,6 @@ API Reference
 
 .. automodule:: returns.io
    :members:
+
+.. automodule:: returns.unsafe
+   :members: