IO monad

Author: sobolevn

CHANGELOG.md

@@ -5,6 +5,18 @@ We follow Semantic Versions since the `0.1.0` release.
 
 ## WIP
 
+### Features
+
+- Adds `IO` marker
+- Adds `unsafe` module with unsafe functions
+- Changes how functions are located inside the project
+
+### Bugfixes
+
+- Fixes container type in `@pipeline`
+- Now `is_successful` is public
+- Now `raise_exception` is public
+
 ### Misc
 
 - Changes how `str()` function works for container types

README.md

@@ -12,7 +12,7 @@ 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/)
+- Enforces better architecture
 - Fully typed with annotations and checked with `mypy`, [PEP561 compatible](https://www.python.org/dev/peps/pep-0561/)
 - Pythonic and pleasant to write and to read (!)
 - Support functions and coroutines, framework agnostic
@@ -27,12 +27,21 @@ pip install returns
 Make sure you know how to get started, [check out our docs](https://returns.readthedocs.io/en/latest/)!
 
 
-## Why?
+## Contents
 
-Consider this code that you can find in **any** `python` project.
+- [Result container](#result-container) that let's you to get rid of exceptions
+- [IO marker](#io-marker) that marks all impure operations and structures them
+
+
+## Result container
+
+Please, make sure that you are also aware of
+[Railway Oriented Programming](https://fsharpforfunandprofit.com/rop/).
 
 ### Straight-forward approach
 
+Consider this code that you can find in **any** `python` project.
+
 ```python
 import requests
 
@@ -84,31 +93,25 @@ just to catch the expected exceptions.
 
 Our code will become complex and unreadable with all this mess!
 
-
 ### Pipeline example
 
-
 ```python
 import requests
-from returns.functions import pipeline, safe
-from returns.result import Result
+from returns.result import Result, pipeline, safe
 
 class FetchUserProfile(object):
     """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
+    @impure
     def _make_request(self, user_id: int) -> requests.Response:
-        response = self._http.get('/api/users/{0}'.format(user_id))
+        response = requests.get('/api/users/{0}'.format(user_id))
         response.raise_for_status()
         return response
 
@@ -141,8 +144,71 @@ And we can clearly see all result patterns that might happen in this particular
 - `Failure[JsonDecodeException]`
 
 And we can work with each of them precisely.
+It is a good practice to create `enum` classes or `Union` types
+with all the possible errors.
+
+
+## IO marker
+
+But is that all we can improve?
+Let's look at `FetchUserProfile` from another angle.
+All its methods looks like a regular ones:
+it is impossible to tell whether they are pure or impure from the first sight.
+
+It leads to a very important consequence:
+*we start to mix pure and impure code together*.
+
+And suffer really bad when testing / reusing it.
+Almost everything should be pure by default.
+And we should explicitly mark impure parts of the program.
+
+### Explicit IO
+
+Let's refactor it to make our `IO` explicit!
+
+```python
+import requests
+from returns.io import IO, impure
+from returns.result import Result, pipeline, safe
+
+class FetchUserProfile(object):
+    """Single responsibility callable object that fetches user profile."""
+
+    @pipeline
+    def __call__(self, user_id: int) -> Result[IO['UserProfile'], Exception]]:
+        """Fetches UserProfile dict from foreign API."""
+        response = self._make_request(user_id).unwrap()
+        return self._parse_json(response)
+
+    @safe
+    @impure
+    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())
+```
+
+Now we have explicit markers where the `IO` did happen
+and these markers cannot be removed.
+
+Whenever we access `FetchUserProfile` we now know
+that it does `IO` and might fail.
+So, we act accordingly!
+
+## More!
 
 What more? [Go to the docs!](https://returns.readthedocs.io)
+Or read these articles:
+
+- [Python exceptions considered an anti-pattern](https://sobolevn.me/2019/02/python-exceptions-considered-an-antipattern)
+- [Enforcing Single Responsibility Principle in Python](https://sobolevn.me/2019/03/enforcing-srp)
 
 ## License
 

docs/index.rst

@@ -18,6 +18,7 @@ Contents
 
   pages/container.rst
   pages/result.rst
+  pages/io.rst
   pages/functions.rst
 
 .. toctree::

docs/pages/functions.rst

@@ -3,210 +3,6 @@ Helper functions
 
 We feature several helper functions to make your developer experience better.
 
-
-is_successful
--------------
-
-:func:`is_succesful <returns.functions.is_successful>` is used to
-tell whether or not your result is a success.
-We treat only treat types that does not throw as a successful ones,
-basically: :class:`Success <returns.result.Success>`.
-
-.. code:: python
-
-  from returns.result import Success, Failure
-  from returns.functions import is_successful
-
-  is_successful(Success(1))
-  # => True
-
-  is_successful(Failure('text'))
-  # => False
-
-.. _pipeline:
-
-pipeline
---------
-
-What is a ``pipeline``?
-It is a more user-friendly syntax to work with containers
-that support both async and regular functions.
-
-Consider this task.
-We were asked to create a method
-that will connect together a simple pipeline of three steps:
-
-1. We validate passed ``username`` and ``email``
-2. We create a new ``Account`` with this data, if it does not exists
-3. We create a new ``User`` associated with the ``Account``
-
-And we know that this pipeline can fail in several places:
-
-1. Wrong ``username`` or ``email`` might be passed, so the validation will fail
-2. ``Account`` with this ``username`` or ``email`` might already exist
-3. ``User`` creation might fail as well,
-   since it also makes an ``HTTP`` request to another micro-service deep inside
-
-Here's the code to illustrate the task.
-
-.. code:: python
-
-  from returns.functions import pipeline
-  from returns.result import Result, Success, Failure
-
-
-  class CreateAccountAndUser(object):
-      """Creates new Account-User pair."""
-
-      # TODO: we need to create a pipeline of these methods somehow...
-
-      # Protected methods
-
-      def _validate_user(
-          self, username: str, email: str,
-      ) -> Result['UserSchema', str]:
-          """Returns an UserSchema for valid input, otherwise a Failure."""
-
-      def _create_account(
-          self, user_schema: 'UserSchema',
-      ) -> Result['Account', str]:
-          """Creates an Account for valid UserSchema's. Or returns a Failure."""
-
-      def _create_user(
-          self, account: 'Account',
-      ) -> Result['User', str]:
-          """Create an User instance. If user already exists returns Failure."""
-
-Using bind technique
-~~~~~~~~~~~~~~~~~~~~
-
-We can implement this feature using a traditional ``bind`` method.
-
-.. code:: python
-
-  class CreateAccountAndUser(object):
-      """Creates new Account-User pair."""
-
-      def __call__(self, username: str, email: str) -> Result['User', str]:
-          """Can return a Success(user) or Failure(str_reason)."""
-          return self._validate_user(username, email).bind(
-              self._create_account,
-          ).bind(
-              self._create_user,
-          )
-
-      # Protected methods
-      # ...
-
-And this will work without any problems.
-But, is it easy to read a code like this? **No**, it is not.
-
-What alternative we can provide? ``@pipeline``!
-
-Using pipeline
-~~~~~~~~~~~~~~
-
-And here's how we can refactor previous version to be more clear.
-
-.. code:: python
-
-  class CreateAccountAndUser(object):
-      """Creates new Account-User pair."""
-
-      @pipeline
-      def __call__(self, username: str, email: str) -> Result['User', str]:
-          """Can return a Success(user) or Failure(str_reason)."""
-          user_schema = self._validate_user(username, email).unwrap()
-          account = self._create_account(user_schema).unwrap()
-          return self._create_user(account)
-
-      # Protected methods
-      # ...
-
-Let's see how this new ``.unwrap()`` method works:
-
-- if you result is ``Success`` it will return its inner value
-- if your result is ``Failure`` it will raise a ``UnwrapFailedError``
-
-And that's where ``@pipeline`` decorator becomes in handy.
-It will catch any ``UnwrapFailedError`` during the pipeline
-and then return a simple ``Failure`` result.
-
-.. mermaid::
-   :caption: Pipeline execution.
-
-   sequenceDiagram
-      participant pipeline
-      participant validation
-      participant account creation
-      participant user creation
-
-      pipeline->>validation: runs the first step
-      validation-->>pipeline: returns Failure(validation message) if fails
-      validation->>account creation: passes Success(UserSchema) if valid
-      account creation-->>pipeline: return Failure(account exists) if fails
-      account creation->>user creation: passes Success(Account) if valid
-      user creation-->>pipeline: returns Failure(http status) if fails
-      user creation-->>pipeline: returns Success(user) if user is created
-
-See, do notation allows you to write simple yet powerful pipelines
-with multiple and complex steps.
-And at the same time the produced code is simple and readable.
-
-And that's it!
-
-
-safe
-----
-
-:func:`safe <returns.functions.safe>` is used to convert
-regular functions that can throw exceptions to functions
-that return :class:`Result <returns.result.Result>` type.
-
-Supports both async and regular functions.
-
-.. code:: python
-
-  from returns.functions import safe
-
-  @safe
-  def divide(number: int) -> float:
-      return number / number
-
-  divide(1)
-  # => Success(1.0)
-
-  divide(0)
-  # => Failure(ZeroDivisionError)
-
-Limitations
-~~~~~~~~~~~
-
-There's one limitation in typing
-that we are facing right now
-due to `mypy issue <https://github.com/python/mypy/issues/3157>`_:
-
-.. code:: python
-
-  from returns.functions import safe
-
-  @safe
-  def function(param: int) -> int:
-      return param
-
-  reveal_type(function)
-  # Actual => def (*Any, **Any) -> builtins.int
-  # Expected => def (int) -> builtins.int
-
-This effect can be reduced
-with the help of `Design by Contract <https://en.wikipedia.org/wiki/Design_by_contract>`_
-with these implementations:
-
-- https://github.com/deadpixi/contracts
-- https://github.com/orsinium/deal
-- https://github.com/Parquery/icontract
-
-
 compose
 -------