Refactors docs to be more IO specific

Author: sobolevn

CHANGELOG.md

@@ -3,6 +3,17 @@
 We follow Semantic Versions since the `0.1.0` release.
 
 
+## WIP
+
+### Features
+
+- New types introduced: `FixableContainer` and `ValueUnwrapContainer`
+
+### Misc
+
+- Improved docs about `IO` and `Container` concept
+
+
 ## 0.7.0
 
 ### Features

docs/pages/container.rst

@@ -4,7 +4,7 @@ Container: the concept
 .. currentmodule:: returns.primitives.container
 
 Container is a concept that allows you
-to write code without traditional error handling
+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.
@@ -15,7 +15,7 @@ Basics
 
 The main idea behind a container is that it wraps some internal state.
 That's what
-:py:attr:`_inner_value <returns.primitives.container.Container._inner_value>`
+:py:attr:`._inner_value <returns.primitives.container.Container._inner_value>`
 is used for.
 
 And we have several functions
@@ -32,10 +32,61 @@ And we can see how this state is evolving during the execution.
        F4                       --> F5["Container(SentNotificationId(992))"]
 
 
+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 other containers of the same type
+
+:func:`.bind <returns.primitives.container.Container.bind>`
+is used to literally bind two different containers together.
+
+.. code:: python
+
+  from returns.result import Result, Success
+
+  def may_fail(user_id: int) -> Result[int, str]:
+      ...
+
+  result = Success(1).bind(may_fail)
+  # => Will be equal to either Success[int] or Failure[str]
+
+And we use :func:`.map <returns.primitives.container.Container.map>`
+to use containers with regular functions.
+
+.. code:: python
+
+  from returns.result import Success
+
+  def double(state: int) -> int:
+      return state * 2
+
+  result = Success(1).map(double)
+  # => Will be equal to Success(2)
+
+The same work with built-in functions as well:
+
+.. code:: python
+
+  from returns.io import IO
+
+  IO('bytes').map(list)
+  # => <IO: ['b', 'y', 't', 'e', 's']>
+
+Note::
+
+  All containers support these methods.
+
+
 Railway oriented programming
 ----------------------------
 
-We use a concept of
+When talking about error handling we use a concept of
 `Railway oriented programming <https://fsharpforfunandprofit.com/rop/>`_.
 It mean that our code can go on two tracks:
 
@@ -73,62 +124,16 @@ or we can rescue the situation.
        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 other containers
-
-:func:`Container.bind <returns.primitives.container.Container.bind>`
-is used to literally bind two different containers together.
-
-.. code:: python
-
-  from returns.result import Result, Success
-
-  def make_http_call(user_id: int) -> Result[int, str]:
-      ...
-
-  result = Success(1).bind(make_http_call)
-  # => Will be equal to either Success[int] or Failure[str]
-
-So, the rule is: whenever you have some impure functions,
-it should return a container type instead.
-
-And we use :func:`Container.map <returns.primitives.container.Container.map>`
-to use containers with `pure functions <https://en.wikipedia.org/wiki/Pure_function>`_.
-
-.. code:: python
-
-  from returns.result import Success
-
-  def double(state: int) -> int:
-      return state * 2
-
-  result = Success(1).map(double)
-  # => Will be equal to Success(2)
-
-Note::
-
-  All containers support these methods.
-
 Returning execution to the right track
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We also support two special methods to work with "failed"
-types like ``Failure`` and ``Nothing``:
+types like ``Failure``:
 
-- :func:`Container.fix <returns.primitives.container.Container.fix>`
+- :func:`.fix <returns.primitives.container.FixableContainer.fix>`
   is the opposite of ``map`` method
   that works only when container is in failed state
-- :func:`Container.rescue <returns.primitives.container.Container.rescue>`
+- :func:`.rescue <returns.primitives.container.FixableContainer.rescue>`
   is the opposite of ``bind`` method
   that works only when container is in failed state
 
@@ -145,20 +150,23 @@ during the pipeline execution:
   Failure(1).fix(double)
   # => Will be equal to Success(2.0)
 
-``rescue`` can return any container type you want.
-It can also fix your flow and get on the successful track again:
+``rescue`` should return one of ``Success`` or ``Failure`` types.
+It can also rescue your flow and get on the successful track again:
 
 .. code:: python
 
   from returns.result import Result, Failure, Success
 
-  def fix(state: Exception) -> Result[int, Exception]:
+  def tolerate_exception(state: Exception) -> Result[int, Exception]:
       if isinstance(state, ZeroDivisionError):
           return Success(0)
       return Failure(state)
 
-  Failure(ZeroDivisionError).rescue(fix)
-  # => Will be equal to Success(0)
+  Failure(ZeroDivisionError()).rescue(tolerate_exception)
+  # => Success(0)
+
+  Failure(ValueError()).rescue(tolerate_exception)
+  # => Failure(ValueError())
 
 Note::
 
@@ -171,9 +179,9 @@ Unwrapping values
 And we have two more functions to unwrap
 inner state of containers into a regular types:
 
-- :func:`Container.value_or <returns.primitives.container.Container.value_or>`
+- :func:`.value_or <returns.primitives.container.ValueUnwrapContainer.value_or>`
   returns a value if it is possible, returns ``default_value`` otherwise
-- :func:`Container.unwrap <returns.primitives.container.Container.unwrap>`
+- :func:`.unwrap <returns.primitives.container.ValueUnwrapContainer.unwrap>`
   returns a value if it is possible, raises ``UnwrapFailedError`` otherwise
 
 .. code:: python
@@ -195,7 +203,7 @@ inner state of containers into a regular types:
 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>`
+use :func:`.failure <returns.primitives.container.FixableContainer.failure>`
 to unwrap the failed state:
 
 .. code:: python

docs/pages/io.rst

@@ -34,6 +34,9 @@ We can later use its result to notify users about their booking request:
 
   notify_user_about_booking_result(is_successful)  # works just fine!
 
+Impure functions
+~~~~~~~~~~~~~~~~
+
 But, imagine that our requirements had changed.
 And now we have to grab the number of already booked tickets
 from some other provider and fetch the maximum capacity from the database:
@@ -57,14 +60,18 @@ It will require to setup:
 - real database and tables
 - fixture data
 - ``requests`` mocks for different outcomes
+- and the whole Universe!
 
 Our complexity has sky-rocketed!
 And the most annoying part is that all other functions
 that call ``can_book_seats`` now also have to do the same setup.
-It seams like ``IO`` is indelible mark.
+It seams like ``IO`` is indelible mark (some people also call it "effect").
 
 And at some point it time we will start to mix pure and impure code together.
 
+Separating two worlds
+~~~~~~~~~~~~~~~~~~~~~
+
 Well, our :py:class:`IO <returns.io.IO>`
 mark is indeed indelible and should be respected.
 
@@ -133,6 +140,7 @@ 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.
 
+
 impure
 ------
 
@@ -145,13 +153,60 @@ you with the existing impure things in Python:
 
   name: IO[str] = impure(input)('What is your name?')
 
+You can also decorate your own functions
+with ``@impure`` for better readability and clearness:
+
+.. code:: python
+
+  import requests
+  from returns.io import impure
+
+  @impure
+  def get_user() -> 'User':
+      return requests.get('https:...').json()
+
 Limitations
 ~~~~~~~~~~~
 
 There's one limitation in typing
 that we are facing right now
 due to `mypy issue <https://github.com/python/mypy/issues/3157>`_.
 
+
+FAQ
+---
+
+What is the difference between IO[T] and T?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+What kind of input parameter should
+my function accept ``IO[T]`` or simple ``T``?
+
+It really depends on your domain / context.
+If the value is pure, than use raw unwrapped values.
+If the value is fetched, input, received, selected, than use ``IO`` container.
+
+Most web applications are just covered with ``IO``.
+
+Why can't we unwrap values or use @pipeline with IO?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Our design decision was not let people unwrap ``IO`` containers,
+so it will indeed infect the whole call-stack with its effect.
+
+Otherwise, people might hack the system
+in some dirty (from our point of view)
+but valid (from the python's point of view) ways.
+
+Warning::
+
+  Of course, you can directly access
+  the internal state of the IO with `._internal_state`,
+  but your are considered to be a grown-up!
+
+  Use wemake-python-styleguide to restrict `._` access in your code.
+
+
 Further reading
 ---------------
 

docs/pages/unsafe.rst

@@ -1,7 +1,7 @@
 unsafe
 ======
 
-Sometimes you really need to get the raw value.
+Sometimes you really need to get the raw value from ``IO`` container.
 For example:
 
 .. code:: python
@@ -12,8 +12,9 @@ For example:
 
 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 ``unsafe_perform_io``:
+What to do? Use :func:`unsafe_perform_io <returns.unsafe.unsafe_perform_io>`:
 
 .. code::
 
@@ -32,6 +33,7 @@ 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>`_
 
+
 API Reference
 -------------
 

returns/functions.py

@@ -8,7 +8,16 @@ def compose(first, second):
     Works as: ``second . first``
     You can read it as "second after first".
 
+    .. code:: python
+
+      from returns.functions import compose
+
+      logged_int = compose(int, print)('123')
+      # => returns: 123
+      # => prints: 123
+
     We can only compose functions with one argument and one return.
+    Type checked.
     """
     return lambda argument: second(first(argument))
 
@@ -17,6 +26,8 @@ def raise_exception(exception):
     """
     Helper function to raise exceptions as a function.
 
+    It might be required as a compatibility tool for existing APIs.
+
     That's how it can be used:
 
     .. code:: python
@@ -25,6 +36,7 @@ def raise_exception(exception):
 
       # Some operation result:
       user: Failure[UserDoesNotExistError]
+
       # Here we unwrap internal exception and raise it:
       user.fix(raise_exception)