Adds do-notation (#1298)

* Initial commit

* Fixes tests

* Fix CI

* Fix CI

* Fix CI

.github/workflows/test.yml

@@ -11,13 +11,14 @@ on:
       - 'docs/requirements.txt'
   workflow_dispatch:
 
-concurrency: 
-  group: ${{ github.head_ref || github.run_id }}
+concurrency:
+  group: test-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    fail-fast: false
     strategy:
       matrix:
         python-version: ['3.7', '3.8', '3.9', '3.10']
@@ -73,7 +74,7 @@ jobs:
         poetry run pytest typesafety -p no:cov -o addopts="" --mypy-ini-file=setup.cfg
 
     - name: Upload coverage to Codecov
-      if: matrix.python-version == 3.8
+      if: ${{ matrix.python-version }} == 3.8
       uses: codecov/[email protected]
       with:
         file: ./coverage.xml

CHANGELOG.md

@@ -5,10 +5,12 @@ Versions before `1.0.0` are `0Ver`-based:
 incremental in minor, bugfixes only are patches.
 See [0Ver](https://0ver.org/).
 
+
 ## 0.19.0 WIP
 
 ### Features
 
+- Adds `do` notation
 - Adds `attempt` decorator
 
 ### Misc

docs/index.rst

@@ -36,6 +36,7 @@ Contents
   pages/converters.rst
   pages/pointfree.rst
   pages/methods.rst
+  pages/do-notation.rst
   pages/functions.rst
   pages/curry.rst
   pages/types.rst

docs/pages/contrib/mypy_plugins.rst

@@ -126,3 +126,12 @@ Pipe
 
 .. automodule:: returns.contrib.mypy._features.pipe
    :members:
+
+Do notation
+~~~~~~~~~~~
+
+.. autoclasstree:: returns.contrib.mypy._features.do_notation
+   :strict:
+
+.. automodule:: returns.contrib.mypy._features.do_notation
+   :members:

docs/pages/do-notation.rst

@@ -0,0 +1,221 @@
+.. _do-notation:
+
+Do Notation
+===========
+
+.. note::
+
+  Technical note: this feature requires :ref:`mypy plugin <mypy-plugins>`.
+
+All containers can be easily composed
+with functions that can take a single argument.
+
+But, what if we need to compose two containers
+with a function with two arguments?
+That's not so easy.
+
+Of course, we can use :ref:`curry` and ``.apply`` or some imperative code.
+But, it is not very easy to write and read.
+
+This is why multiple functional languages have a concept of "do-notation".
+It allows you to write beautiful imperative code.
+
+
+Regular containers
+------------------
+
+Let's say we have a function called ``add`` which is defined like this:
+
+.. code:: python
+
+  >>> def add(one: int, two: int) -> int:
+  ...     return one + two
+
+And we have two containers: ``IO(2)`` and ``IO(3)``.
+How can we easily get ``IO(5)`` in this case?
+
+Luckily, ``IO`` defines :meth:`returns.io.IO.do` which can help us:
+
+.. code:: python
+
+  >>> from returns.io import IO
+
+  >>> assert IO.do(
+  ...     add(first, second)
+  ...     for first in IO(2)
+  ...     for second in IO(3)
+  ... ) == IO(5)
+
+Notice, that you don't have two write any complicated code.
+Everything is pythonic and readable.
+
+However, we still need to explain what ``for`` does here.
+It uses Python's ``__iter__`` method which returns an iterable
+with strictly a single raw value inside.
+
+.. warning::
+
+  Please, don't use ``for x in container`` outside of do-notation.
+  It does not make much sense.
+
+Basically, for ``IO(2)`` it will return just ``2``.
+Then, ``IO.do`` wraps it into ``IO`` once again.
+
+Errors
+~~~~~~
+
+Containers like ``Result`` and ``IOResult`` can sometimes represent errors.
+In this case, do-notation expression will return the first found error.
+
+For example:
+
+.. code:: python
+
+  >>> from returns.result import Success, Failure, Result
+
+  >>> assert Result.do(
+  ...     first + second
+  ...     for first in Failure('a')
+  ...     for second in Success(3)
+  ... ) == Failure('a')
+
+This behavior is consistent with ``.map`` and other methods.
+
+
+Async containers
+----------------
+
+We also support async containers like ``Future`` and ``FutureResult``.
+It works in a similar way as regular sync containers.
+But, they require ``async for`` expressions instead of regular ``for`` ones.
+And because of that - they cannot be used outsided of ``async def`` context.
+
+Usage example:
+
+.. code:: python
+
+  >>> import anyio
+  >>> from returns.future import Future
+  >>> from returns.io import IO
+
+  >>> async def main() -> None:
+  ...     return await Future.do(
+  ...         first + second
+  ...         async for first in Future.from_value(1)
+  ...         async for second in Future.from_value(2)
+  ...     )
+
+  >>> assert anyio.run(main) == IO(3)
+
+
+FAQ
+---
+
+Why don't we allow mixing different container types?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One might ask, why don't we allow mixing multiple container types
+in a single do-notation expression?
+
+For example, this code will not what you expect:
+
+.. code:: python
+
+  >>> from returns.result import Result, Success
+  >>> from returns.io import IOResult, IOSuccess
+
+  >>> assert Result.do(
+  ...     first + second
+  ...     for first in Success(2)
+  ...     for second in IOSuccess(3)  # Notice the IO part here
+  ... ) == Success(5)
+
+This code will raise a mypy error at ``for second in IOSuccess(3)`` part:
+
+.. code::
+
+  Invalid type supplied in do-notation: expected "returns.result.Result[Any, Any]", got "returns.io.IOSuccess[builtins.int*]"
+
+Notice, that the ``IO`` part is gone in the final result. This is not right.
+And we can't track this in any manner.
+So, we require all containers to have the same type.
+
+The code above must be rewritten as:
+
+.. code:: python
+
+  >>> from returns.result import Success
+  >>> from returns.io import IOResult, IOSuccess
+
+  >>> assert IOResult.do(
+  ...     first + second
+  ...     for first in IOResult.from_result(Success(2))
+  ...     for second in IOSuccess(3)
+  ... ) == IOSuccess(5)
+
+Now, it is correct. ``IO`` part is safe, the final result is correct.
+And mypy is happy.
+
+Why don't we allow ``if`` conditions in generator expressions?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the moment, using ``if`` conditions inside generator expressions
+passed into ``.do`` method is not allowed. Why?
+
+Because if the ``if`` condition will return ``False``,
+we will have an empty iterable and ``StopIteration`` will be thrown.
+
+.. code:: python
+
+  >>> from returns.io import IO
+
+  >>> IO.do(
+  ...     first + second
+  ...     for first in IO(2)
+  ...     for second in IO(3)
+  ...     if second > 10
+  ... )
+  Traceback (most recent call last):
+    ...
+  StopIteration
+
+It will raise:
+
+.. code::
+
+  Using "if" conditions inside a generator is not allowed
+
+Instead, use conditions and checks inside your logic, not inside your generator.
+
+Why do we require a literal expression in do-notation?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This code will work in runtime, but will raise a mypy error:
+
+.. code:: python
+
+  >>> from returns.result import Result, Success
+
+  >>> expr = (
+  ...     first + second
+  ...     for first in Success(2)
+  ...     for second in Success(3)
+  ... )
+  >>>
+  >>> assert Result.do(expr) == Success(5)
+
+It raises:
+
+.. code::
+
+  Literal generator expression is required, not a variable or function call
+
+This happens, because of mypy's plugin API.
+We need the whole expression to make sure it is correct.
+We cannot use variables and function calls in its place.
+
+
+Further reading
+---------------
+
+- `Do notation in Haskell <https://en.wikibooks.org/wiki/Haskell/do_notation>`_