Fixes #83

Author: sobolevn

README.md

@@ -181,24 +181,22 @@ class FetchUserProfile(object):
     """Single responsibility callable object that fetches user profile."""
 
     @pipeline
-    def __call__(self, user_id: int) -> Result[IO['UserProfile'], Exception]:
+    def __call__(self, user_id: int) -> IO[Result['UserProfile', Exception]]:
         """Fetches UserProfile dict from foreign API."""
-        response = self._make_request(user_id).unwrap()
-        return self._parse_json(response)
+        return self._make_request(user_id).map(
+            lambda response: self._parse_json(response.unwrap())
+        )
 
-    @safe
     @impure
+    @safe
     def _make_request(self, user_id: int) -> requests.Response:
         response = requests.get('/api/users/{0}'.format(user_id))
         response.raise_for_status()
         return response
 
     @safe
-    def _parse_json(
-        self,
-        io_response: IO[requests.Response],
-    ) -> IO['UserProfile']:
-        return io_response.map(lambda response: response.json())
+    def _parse_json(self,response: requests.Response) -> 'UserProfile':
+        return response.json()
 ```
 
 Now we have explicit markers where the `IO` did happen

docs/pages/container.rst

@@ -7,7 +7,13 @@ Container is a concept that allows you
 to write code around the existing wrapped values
 while maintaining the execution context.
 
-We will show you its simple API of one attribute and several simple methods.
+List of supported containers:
+
+- :class:`IO <returns.io.IO>` to mark explicit ``IO`` actions
+- :class:`Result <returns.result.Result>` to handle possible exceptions
+
+We will show you container's simple API of one attribute
+and several simple methods.
 
 
 Basics
@@ -268,6 +274,19 @@ You can have a look at the suggested ``mypy``
 in our own repository.
 
 
+Composition
+-----------
+
+You can and should compose different containers together.
+Here's the full table of compositions that make sense:
+
+- ``IO[Result[A, B]]`` ✅
+- ``IO[IO[A]]`` 🚫
+- ``Result[IO[A], B]`` 🚫
+- ``Result[A, IO[A]]`` 🚫
+- ``Result[Result[A, B], C]`` 🚫
+- ``Result[A, Result[B, C]]`` 🚫
+
 API Reference
 -------------