Makes monads immutable, adds more docs

Author: sobolevn

docs/pages/do-notation.rst

@@ -1,3 +1,5 @@
+.. _do-notation:
+
 Do notation
 ===========
 

docs/pages/monad.rst

@@ -1,6 +1,144 @@
 Monad: the concept
 ==================
 
+.. currentmodule:: dry_monads.primitives.monads
+
+We won't say that monad is `a monoid in the category of endofunctors <https://stackoverflow.com/questions/3870088/a-monad-is-just-a-monoid-in-the-category-of-endofunctors-whats-the-problem>`_.
+
+Monad is a concept that allows you
+to write code without traditional error handling
+while maintaining the execution context.
+
+We will show you its simple API of one attribute and several simple methods.
+
+Internals
+---------
+
+The main idea behind a monad is that it wraps some internal state.
+That's what
+:py:attr:`Monad._inner_value <dry_monads.primitives.monad.Monad._inner_value>`
+is used for.
+
+And we have several functions to create new monads based on the previous state.
+And we can see how this state is evolving during the execution.
+
+.. mermaid::
+  :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))"]
+
+Creating new monads
+~~~~~~~~~~~~~~~~~~~
+
+We use two methods to create new monads from the previous one.
+``bind`` and ``fmap``.
+
+The difference is simple:
+
+- ``fmap`` works with functions that return regular values
+- ``bind`` works with functions that return monads
+
+:func:`Monad.bind <dry_monads.primitives.monad.Monad.bind>`
+is used to literally bind two different monads together.
+
+.. code:: python
+
+  from dry_monads.either import Either, Success
+
+  def make_http_call(user_id: int) -> Either[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 monad instead.
+
+And we use :func:`Monad.fmap <dry_monads.primitives.monad.Monad.fmap>`
+to use monads with pure functions.
+
+.. code:: python
+
+  from dry_monads.either import Success
+
+  def double(state: int) -> int:
+      return state * 2
+
+  result = Success(1).fmap(double)
+  # => will be equal to Success(2)
+
+Unwrapping values
+~~~~~~~~~~~~~~~~~
+
+And we have two more functions to unwrap
+inner state of monads into a regular types:
+
+- :func:`Monad.value_or <dry_monads.primitives.monad.Monad.value_or>` - returns
+  a value if it is possible, returns ``default_value`` otherwise
+- :func:`Monad.unwrap <dry_monads.primitives.monad.Monad.unwrap>` - returns
+  a value if it possible, raises ``UnwrapFailedError`` otherwise
+
+.. code:: python
+
+  from dry_monads.either import Failure, Success
+
+  Success(1).value_or(None)
+  # => 1
+
+  Success(0).unwrap()
+  # => 0
+
+  Failure(1).value_or(default_value=100)
+  # => 100
+
+  Failure(1).unwrap()
+  # => Traceback (most recent call last): UnwrapFailedError
+
+The most user-friendly way to use ``unwrap`` method is with :ref:`do-notation`.
+
+Immutability
+------------
+
+We like to think of ``dry-monads`` as immutable structures.
+You cannot mutate the inner state of the created monad,
+because we redefine ``__setattr__`` and ``__delattr__`` magic methods.
+
+You cannot also set new attributes to monad instances,
+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 ``fmap`` and ``bind`` methods.
+
+So, instead of:
+
+.. code:: python
+
+  some_monad.fmap(lambda x: x + 2)  #: Callable[[Any], Any]
+
+Write:
+
+.. code:: python
+
+  from functools import partial
+
+  def increment(addition: int, number: int) -> int:
+      return number + addition
+
+  some_monad.fmap(partial(increment, 2))  #: functools.partial[builtins.int*]
+
+This way your code will be type-safe from errors.
+
 API Reference
 -------------
 

dry_monads/either.py

@@ -53,7 +53,7 @@ def __init__(self, inner_value: ErrorType) -> None:
 
         'value' is any arbitrary value of any type including functions.
         """
-        self._inner_value = inner_value
+        object.__setattr__(self, '_inner_value', inner_value)
 
     def fmap(self, function) -> 'Left[ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
@@ -86,7 +86,7 @@ def __init__(self, inner_value: ValueType) -> None:
 
         'value' is any arbitrary value of any type including functions.
         """
-        self._inner_value = inner_value
+        object.__setattr__(self, '_inner_value', inner_value)
 
     def fmap(
         self,

dry_monads/primitives/exceptions.py

@@ -18,3 +18,7 @@ def __init__(self, monad: 'MonadType') -> None:
         """
         super().__init__()
         self.halted_monad = monad
+
+
+class ImmutableStateError(Exception):
+    """Raised when a monad is forced to be mutated."""

dry_monads/primitives/monad.py

@@ -1,13 +1,43 @@
 # -*- coding: utf-8 -*-
 
 from abc import ABCMeta, abstractmethod
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic, NoReturn, TypeVar
+
+from dry_monads.primitives.exceptions import ImmutableStateError
 
 ValueType = TypeVar('ValueType')
 NewValueType = TypeVar('NewValueType')
 
 
-class Monad(Generic[ValueType], metaclass=ABCMeta):
+class _BaseMonad(Generic[ValueType], metaclass=ABCMeta):
+    """Utility class to provide all needed magic methods to the contest."""
+
+    __slots__ = ('_inner_value',)
+    _inner_value: Any
+
+    def __setattr__(self, attr_name, attr_value) -> NoReturn:
+        """Makes inner state of the monads immutable."""
+        raise ImmutableStateError()
+
+    def __delattr__(self, attr_name) -> NoReturn:  # noqa: Z434
+        """Makes inner state of the monads immutable."""
+        raise ImmutableStateError()
+
+    def __str__(self) -> str:
+        """Converts to string."""
+        return '{0}: {1}'.format(
+            self.__class__.__qualname__,
+            str(self._inner_value),
+        )
+
+    def __eq__(self, other) -> bool:
+        """Used to compare two 'Monad' objects."""
+        if not isinstance(other, _BaseMonad):
+            return False
+        return self._inner_value == other._inner_value  # noqa: Z441
+
+
+class Monad(_BaseMonad[ValueType]):
     """
     Represents a "context" in which calculations can be executed.
 
@@ -17,9 +47,12 @@ class Monad(Generic[ValueType], metaclass=ABCMeta):
     a series of calculations while maintaining
     the context of that specific monad.
 
-    """
+    This is an abstract class with the API declaration.
 
-    _inner_value: Any
+    Attributes:
+        _inner_value: Wrapped internal immutable state.
+
+    """
 
     @abstractmethod
     def fmap(self, function):  # pragma: no cover
@@ -53,16 +86,3 @@ def unwrap(self) -> ValueType:  # pragma: no cover
         And for ones that raise an exception for no values.
         """
         raise NotImplementedError()
-
-    def __str__(self) -> str:
-        """Converts to string."""
-        return '{0}: {1}'.format(
-            self.__class__.__qualname__,
-            str(self._inner_value),
-        )
-
-    def __eq__(self, other) -> bool:
-        """Used to compare two 'Monad' objects."""
-        if not isinstance(other, Monad):
-            return False
-        return self._inner_value == other._inner_value  # noqa: Z441

setup.cfg

@@ -77,7 +77,6 @@ warn_unused_ignores = True
 warn_redundant_casts = True
 warn_unused_configs = True
 
-
 [doc8]
 ignore-path = docs/_build
 max-line-length = 80

tests/test_either/test_equality.py

@@ -1,6 +1,9 @@
 # -*- coding: utf-8 -*-
 
+import pytest
+
 from dry_monads.either import Left, Right
+from dry_monads.primitives.exceptions import ImmutableStateError
 
 
 def test_nonequality():
@@ -9,3 +12,33 @@ def test_nonequality():
 
     assert Left(input_value) != input_value
     assert Right(input_value) != input_value
+
+
+def test_immutability_failure():
+    """Ensures that Failure monad is immutable."""
+    with pytest.raises(ImmutableStateError):
+        Left(0)._inner_state = 1  # noqa: Z441
+
+    with pytest.raises(ImmutableStateError):
+        Left(1).missing = 2
+
+    with pytest.raises(ImmutableStateError):
+        del Left(0)._inner_state  # type: ignore # noqa: Z420, Z441
+
+    with pytest.raises(AttributeError):
+        Left(1).missing  # type: ignore # noqa: Z444
+
+
+def test_immutability_success():
+    """Ensures that Success monad is immutable."""
+    with pytest.raises(ImmutableStateError):
+        Right(0)._inner_state = 1  # noqa: Z441
+
+    with pytest.raises(ImmutableStateError):
+        Right(1).missing = 2
+
+    with pytest.raises(ImmutableStateError):
+        del Right(0)._inner_state  # type: ignore # noqa: Z420, Z441
+
+    with pytest.raises(AttributeError):
+        Right(1).missing  # type: ignore # noqa: Z444