Working on docs

Author: sobolevn

README.md

@@ -14,8 +14,9 @@ Make your functions return something meaningful, typed, and safe!
 ## Features
 
 - Provides a bunch of primitives to write declarative business logic
+- Enforces [Railway Oriented Programming](https://fsharpforfunandprofit.com/rop/)
 - Fully typed with annotations and checked with `mypy`,
-  allowing you to write type-safe code as well
+  allowing you to write type-safe code as well, [PEP561 compatible](https://www.python.org/dev/peps/pep-0561/)
 - Pythonic and pleasant to write and to read (!)
 
 
@@ -28,6 +29,7 @@ pip install returns
 
 Make sure you know how to get started, [checkout our docs](https://returns.readthedocs.io/en/latest/)!
 
+
 ## Why?
 
 Consider this code that you can find in **any** `python` project.
@@ -37,52 +39,50 @@ Consider this code that you can find in **any** `python` project.
 ```python
 import requests
 
-
 def fetch_user_profile(user_id: int) -> 'UserProfile':
     """Fetches UserProfile dict from foreign API."""
     response = requests.get('/api/users/{0}'.format(user_id))
     response.raise_for_status()
     return response.json()
 ```
 
-Seems legit, does not it? 
-It also seems like a pretty straight forward code to test. 
+Seems legit, does not it?
+It also seems like a pretty straight forward code to test.
 All you need is to mock `requests.get` to return the structure you need.
 
-But, there are hidden problems in this tiny code sample 
+But, there are hidden problems in this tiny code sample
 that are almost impossible to spot at the first glance.
 
 ### Hidden problems
 
-
-The same exact code, but with the problems explained.
+Let's have a look at the exact same code,
+but with the all hidden problems explained.
 
 ```python
 import requests
 
-
 def fetch_user_profile(user_id: int) -> 'UserProfile':
     """Fetches UserProfile dict from foreign API."""
     response = requests.get('/api/users/{0}'.format(user_id))
-    
-    # What if we try to find user that does not exist? 
+
+    # What if we try to find user that does not exist?
     # Or network will go down? Or the server will return 500?
     # In this case the next line will fail with an exception.
-    # We need to handle all possible errors in this function 
+    # We need to handle all possible errors in this function
     # and do not return corrupt data to consumers.
     response.raise_for_status()
 
-    # What if we have received invalid JSON? 
+    # What if we have received invalid JSON?
     # Next line will raise an exception!
     return response.json()
 ```
 
-Now, all (probably all?) problems are clear. 
-How can we be sure that this function will be safe 
+Now, all (probably all?) problems are clear.
+How can we be sure that this function will be safe
 to use inside our complex business logic?
 
-We really can not be sure! 
-We will have to create **lots** of `try` and `except` cases 
+We really can not be sure!
+We will have to create **lots** of `try` and `except` cases
 just to catch the expected exceptions.
 
 Our code will become complex and unreadable with all this mess!
@@ -96,26 +96,25 @@ import requests
 from returns.functions import pipeline, safe
 from returns.result import Result
 
-
 class FetchUserProfile(object):
-    """Single responibility callable object that fetches user profiles."""
-    
-    #: You can later use dependency injection to replace `requests` 
-    #: with any other http library you want.
+    """Single responsibility callable object that fetches user profile."""
+
+    #: You can later use dependency injection to replace `requests`
+    #: with any other http library (or even a custom service).
     _http = requests
-    
+
     @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)
-        
+
     @safe
     def _make_request(self, user_id: int) -> requests.Response:
         response = self._http.get('/api/users/{0}'.format(user_id))
         response.raise_for_status()
         return response
-        
+
     @safe
     def _parse_json(self, response: requests.Response) -> 'UserProfile':
         return response.json()
@@ -124,18 +123,18 @@ class FetchUserProfile(object):
 Now we have a clean and a safe way to express our business need.
 We start from making a request, that might fail at any moment.
 
-Now, instead of returning a regular value 
+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)
 decorator.
 
-It will return [Success[Response] or Failure[Exception]](https://returns.readthedocs.io/en/latest/pages/result.html). 
+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) 
+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]`!
 
@@ -144,6 +143,9 @@ And we can clearly see all result patterns that might happen in this particular
 - `Failure[HttpException]`
 - `Failure[JsonDecodeException]`
 
+And we can work with each of them precisely.
+
+What more? [Go to the docs!](https://returns.readthedocs.io)
 
 ## License
 

docs/pages/container.rst

@@ -9,8 +9,9 @@ while maintaining the execution context.
 
 We will show you its simple API of one attribute and several simple methods.
 
-Internals
----------
+
+Basics
+------
 
 The main idea behind a container is that it wraps some internal state.
 That's what
@@ -25,21 +26,65 @@ And we can see how this state is evolving during the execution.
   :caption: State evolution.
 
    graph LR
-       F1["State()"] --> F2["State(UserId(1))"]
-       F2            --> F3["State(UserAccount(156))"]
-       F3            --> F4["State(FailedLoginAttempt(1))"]
-       F4            --> F5["State(SentNotificationId(992))"]
+       F1["Container(Initial)"] --> F2["Container(UserId(1))"]
+       F2                       --> F3["Container(UserAccount(156))"]
+       F3                       --> F4["Container(FailedLoginAttempt(1))"]
+       F4                       --> F5["Container(SentNotificationId(992))"]
+
+
+Railway oriented programming
+----------------------------
+
+We use a concept of
+`Railway oriented programming <https://fsharpforfunandprofit.com/rop/>`_.
+It mean that our code can go on two tracks:
+
+1. Successful one: where everything goes perfectly: HTTP requests work,
+   database is always serving us data, parsing values does not failed
+2. Failed one: where something went wrong
+
+We can switch from track to track: we can fail something
+or we can rescue the situation.
+
+.. mermaid::
+  :caption: Railway oriented programming.
+
+   graph LR
+       S1 --> S3
+       S3 --> S5
+       S5 --> S7
+
+       F2 --> F4
+       F4 --> F6
+       F6 --> F8
 
-Creating new containers
-~~~~~~~~~~~~~~~~~~~~~~~
+       S1 -- Fail --> F2
+       F2 -- Fix --> S3
+       S3 -- Fail --> F4
+       S5 -- Fail --> F6
+       F6 -- Rescue --> S7
+
+       style S1 fill:green
+       style S3 fill:green
+       style S5 fill:green
+       style S7 fill:green
+       style F2 fill:red
+       style F4 fill:red
+       style F6 fill:red
+       style F8 fill:red
+
+
+
+Working with containers
+-----------------------
 
 We use two methods to create new containers from the previous one.
 ``bind`` and ``map``.
 
 The difference is simple:
 
 - ``map`` works with functions that return regular values
-- ``bind`` works with functions that return containers
+- ``bind`` works with functions that return other containers
 
 :func:`Container.bind <returns.primitives.container.Container.bind>`
 is used to literally bind two different containers together.
@@ -70,8 +115,8 @@ to use containers with `pure functions <https://en.wikipedia.org/wiki/Pure_funct
   result = Success(1).map(double)
   # => Will be equal to Success(2)
 
-Reverse operations
-~~~~~~~~~~~~~~~~~~
+Returning execution to the right track
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We also support two special methods to work with "failed"
 types like ``Failure`` and ``Nothing``:
@@ -138,7 +183,7 @@ inner state of containers into a regular types:
   Failure(1).unwrap()
   # => Traceback (most recent call last): UnwrapFailedError
 
-The most user-friendly way to use ``unwrap`` method is with :ref:`do-notation`.
+The most user-friendly way to use ``unwrap`` method is with :ref:`pipeline`.
 
 For failing containers you can
 use :func:`Container.failure <returns.primitives.container.Container.failure>`
@@ -155,6 +200,7 @@ to unwrap the failed state:
 Be careful, since this method will raise an exception
 when you try to ``failure`` a successful container.
 
+
 Immutability
 ------------
 
@@ -167,32 +213,25 @@ since we are using ``__slots__`` for better performance and strictness.
 
 Well, nothing is **really** immutable in python, but you were warned.
 
-Using lambda functions
-----------------------
 
-Please, do not use ``lambda`` functions in ``python``. Why?
-Because all ``lambda`` functions arguments are typed as ``Any``.
-This way you won't have any practical typing features
-from ``map`` and ``bind`` methods.
+Type safety
+-----------
 
-So, instead of:
+We try to make our containers optionally type safe.
 
-.. code:: python
-
-  some_container.map(lambda x: x + 2)  #: Callable[[Any], Any]
-
-Write:
-
-.. code:: python
+What does it mean?
 
-  from functools import partial
+1. It is still good old ``python``, do whatever you want without ``mypy``
+2. If you are using ``mypy`` you will be notified about type violations
 
-  def increment(addition: int, number: int) -> int:
-      return number + addition
+We also ship `PEP561 <https://www.python.org/dev/peps/pep-0561/>`_
+compatible ``.pyi`` files together with the source code.
+In this case these types will be available to users
+when they install our application.
 
-  some_container.map(partial(increment, 2))  # functools.partial[builtins.int]
+However, this is still good old ``python`` type system,
+and it has its drawbacks.
 
-This way your code will be type-safe from errors.
 
 API Reference
 -------------

docs/pages/functions.rst

@@ -25,6 +25,7 @@ and :class:`Some <returns.maybe.Some>`.
   is_successful(Nothing) or is_successful(Failure('text'))
   # => False
 
+.. _pipeline:
 
 pipeline
 --------