Closes #686

Author: sobolevn

docs/pages/context.rst

@@ -319,72 +319,8 @@ Which means that it is a wrapper around impure async function that might fail.
 
 Here's how it should be used:
 
-.. code:: python
-
-  from typing import Callable, Sequence
-
-  import anyio  # you would need to `pip install anyio`
-  import httpx  # you would need to `pip install httpx`
-  from typing_extensions import Final, TypedDict
-
-  from returns.context import RequiresContextFutureResultE
-  from returns.functions import tap
-  from returns.future import FutureResultE, future_safe
-  from returns.iterables import Fold
-  from returns.pipeline import managed
-  from returns.result import safe
-
-  _URL: Final = 'https://jsonplaceholder.typicode.com/posts/{0}'
-  _Post = TypedDict('_Post', {
-      'id': int,
-      'userId': int,
-      'title': str,
-      'body': str,
-  })
-  _TitleOnly = TypedDict('_TitleOnly', {'title': str})
-
-  def _close(client: httpx.AsyncClient, _) -> FutureResultE[None]:
-      return future_safe(client.aclose)()
-
-  def _fetch_post(
-      post_id: int,
-  ) -> RequiresContextFutureResultE[_Post, httpx.AsyncClient]:
-      context: RequiresContextFutureResultE[
-          httpx.AsyncClient,
-          httpx.AsyncClient,
-      ] = RequiresContextFutureResultE.ask()
-
-      return context.bind_future_result(
-          lambda client: future_safe(client.get)(_URL.format(post_id)),
-      ).bind_result(
-          safe(tap(httpx.Response.raise_for_status)),
-      ).map(
-          lambda response: response.json(),
-      )
-
-  def show_titles(
-      number_of_posts: int,
-  ) -> RequiresContextFutureResultE[Sequence[_TitleOnly], httpx.AsyncClient]:
-      titles = [
-          # Notice how easily we compose async and sync functions:
-          _fetch_post(post_id).map(lambda post: post['title'])
-          # TODO: try `for post_id in {2, 1, 0}:` to see how errors work
-          for post_id in range(1, number_of_posts + 1)
-      ]
-      return Fold.collect(titles, RequiresContextFutureResultE.from_value(()))
-
-  if __name__ == '__main__':
-      # Let's fetch 3 titles of posts asynchronously:
-      managed_httpx = managed(show_titles(3), _close)
-      future_result = managed_httpx(
-          FutureResultE.from_value(httpx.AsyncClient(timeout=5)),
-      )
-      print(anyio.run(future_result.awaitable))
-      # <IOResult: <Success: (
-      #    'sunt aut facere repellat provident occaecati ...',
-      #    'qui est esse',
-      #    'ea molestias quasi exercitationem repellat qui ipsa sit aut',
-      # )>>
+.. literalinclude:: ../../tests/test_examples/test_context/test_reader_future_result.py
+   :linenos:
 
 This example illustrates the whole point of our actions: writting
 sync code that executes asynchronously without any magic at all!

docs/pages/create-your-own-container.rst

@@ -138,7 +138,7 @@ Looks like it already knows what methods should be there!
 Ok, let's drop some initial and straight forward implementation.
 We will later make it more complex step by step.
 
-.. literalinclude:: ../../tests/test_examples/test_pair1.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair1.py
    :linenos:
 
 You can check our resulting source with ``mypy``. It would be happy this time.
@@ -159,17 +159,17 @@ It would be also nice to add all other interfaces there as supertypes.
 
 That's how it is going to look:
 
-.. literalinclude:: ../../tests/test_examples/test_pair2.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair2.py
    :linenos:
    :pyobject: PairLikeN
 
 Awesome! Now we have a new interface to implement. Let's do that!
 
-.. literalinclude:: ../../tests/test_examples/test_pair2.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair2.py
    :linenos:
    :pyobject: Pair.pair
 
-.. literalinclude:: ../../tests/test_examples/test_pair2.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair2.py
    :linenos:
    :pyobject: Pair.from_unpaired
 
@@ -194,7 +194,7 @@ This gives us several key benefits:
 
 Let's add docs and doctests! Let's use ``map`` method as a short example:
 
-.. literalinclude:: ../../tests/test_examples/test_pair3.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair3.py
    :linenos:
    :pyobject: Pair.map
 
@@ -215,13 +215,13 @@ Let's add them to our ``PairLikeN`` interface.
 
 Let's start with laws definition:
 
-.. literalinclude:: ../../tests/test_examples/test_pair4.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair4.py
    :linenos:
    :pyobject: _LawSpec
 
 And them let's add them to our ``PairLikeN`` interface:
 
-.. literalinclude:: ../../tests/test_examples/test_pair4.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair4.py
    :linenos:
    :pyobject: PairLikeN
    :emphasize-lines: 9-12
@@ -231,7 +231,7 @@ to generate 10 ``hypothesis`` test cases with hundreds real test cases inside.
 
 Here's the final result of our brand new ``Pair`` type:
 
-.. literalinclude:: ../../tests/test_examples/test_pair4.py
+.. literalinclude:: ../../tests/test_examples/test_your_container/test_pair4.py
    :linenos:
 
 
@@ -258,12 +258,12 @@ to make sure our ``.pair`` function works correctly:
   We need it since we store our example in ``tests/`` folder.
   And we have to tell ``mypy`` how to find it.
 
-.. literalinclude:: ../../typesafety/test_examples/test_pair4_def.yml
+.. literalinclude:: ../../typesafety/test_examples/test_your_container/test_pair4_def.yml
    :linenos:
 
 Ok, now, let's try to raise an error by using it incorrectly:
 
-.. literalinclude:: ../../typesafety/test_examples/test_pair4_error.yml
+.. literalinclude:: ../../typesafety/test_examples/test_your_container/test_pair4_error.yml
    :linenos:
 
 
@@ -280,7 +280,7 @@ So, let's say we want to use native :func:`~returns.pointfree.map.map_`
 pointfree function with our new ``Pair`` type.
 Let's test that it will work correctly:
 
-.. literalinclude:: ../../typesafety/test_examples/test_pair4_reuse.yml
+.. literalinclude:: ../../typesafety/test_examples/test_your_container/test_pair4_reuse.yml
    :linenos:
 
 Yes, it works!

docs/pages/future.rst

@@ -81,51 +81,8 @@ And is literally a wrapper around ``Future[Result[_V, _E]]`` type.
 
 Let's see how it can be used in a real program:
 
-.. code:: python
-
-  from typing import Sequence
-
-  import anyio  # you would need to `pip install anyio`
-  import httpx  # you would need to `pip install httpx`
-  from typing_extensions import Final, TypedDict
-
-  from returns.future import FutureResultE, future_safe
-  from returns.iterables import Fold
-
-  _URL: Final = 'https://jsonplaceholder.typicode.com/posts/{0}'
-  _Post = TypedDict('_Post', {
-      'id': int,
-      'userId': int,
-      'title': str,
-      'body': str,
-  })
-  _TitleOnly = TypedDict('_TitleOnly', {'title': str})
-
-  @future_safe
-  async def _fetch_post(post_id: int) -> _Post:
-      # Ideally, we can use `ReaderFutureResult` to provide `client` from deps.
-      async with httpx.AsyncClient(timeout=5) as client:
-          response = await client.get(_URL.format(post_id))
-          response.raise_for_status()
-          return response.json()
-
-  def show_titles(number_of_posts: int) -> FutureResultE[Sequence[_TitleOnly]]:
-      titles = [
-          # Notice how easily we compose async and sync functions:
-          _fetch_post(post_id).map(lambda post: post['title'])
-          # TODO: try `for post_id in {2, 1, 0}:` to see how errors work
-          for post_id in range(1, number_of_posts + 1)
-      ]
-      return Fold.collect(titles, FutureResultE.from_value(()))
-
-  if __name__ == '__main__':
-      # Let's fetch 3 titles of posts asynchronously:
-      print(anyio.run(show_titles(3).awaitable))
-      # <IOResult: <Success: (
-      #    'sunt aut facere repellat provident occaecati ...',
-      #    'qui est esse',
-      #    'ea molestias quasi exercitationem repellat qui ipsa sit aut',
-      # )>>
+.. literalinclude:: ../../tests/test_examples/test_future/test_future_result.py
+   :linenos:
 
 What is different?
 

poetry.lock

@@ -60,16 +60,18 @@ typing-extensions = "^3.7"
 
 
 [tool.poetry.dev-dependencies]
+anyio = "^2.0"
+curio = "^1.4"
+trio = "^0.17"
+attrs = "^20.2"
+httpx = "^0.16"
+
 mypy = "^0.790"
 wemake-python-styleguide = "^0.14"
 flake8-pytest-style = "^1.2"
 flake8-pyi = "^20.10"
 nitpick = "^0.23"
 
-anyio = "^2.0"
-curio = "^1.4"
-trio = "^0.17"
-
 safety = "^1.8"
 
 pytest = "^6.1"
@@ -88,4 +90,3 @@ sphinx-hoverxref = "^0.5b1"
 doc8 = "^0.8"
 m2r = "^0.2"
 tomlkit = "^0.7"
-attrs = "^20.2"