Merge pull request #1 from sobolevn/feature-do-notation

Started working on do-notation

Author: sobolevn

README.md

@@ -9,16 +9,17 @@ Monads for `python` made simple and safe.
 
 - Provides primitives to write declarative business logic
 - Fully typed with annotations and checked with `mypy`,
-  making your code type-safe as well
+  allowing you to write type-safe code as well
+- No operator overloading or other unpythonic stuff that makes your eyes bleed
 
 
 ## Inspirations
 
 This module is heavily based on:
 
-- https://github.com/dry-rb/dry-monads
-- https://github.com/dbrattli/OSlash
-- https://bitbucket.org/jason_delaat/pymonad
+- [dry-rb/dry-monads](https://github.com/dry-rb/dry-monads)
+- [Ø](https://github.com/dbrattli/OSlash)
+- [pymonad](https://bitbucket.org/jason_delaat/pymonad)
 
 
 ## License

dry_monads/do_notation.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+from functools import wraps
+from typing import Callable
+
+from dry_monads.primitives.exceptions import UnwrapFailedError
+from dry_monads.primitives.types import MonadType
+
+
+def do_notation(
+    function: Callable[..., MonadType],
+) -> Callable[..., MonadType]:
+    """Decorator to enable 'do-notation' context."""
+    @wraps(function)
+    def decorator(*args, **kwargs) -> MonadType:
+        try:
+            return function(*args, **kwargs)
+        except UnwrapFailedError as exc:
+            return exc.halted_monad
+    return decorator

dry_monads/either.py

@@ -1,49 +1,93 @@
 # -*- coding: utf-8 -*-
 
-from typing import Callable
+from abc import ABCMeta, abstractmethod
+from typing import Any, Callable, Generic, NoReturn, TypeVar, Union
 
+from typing_extensions import final
+
+from dry_monads.primitives.exceptions import UnwrapFailedError
 from dry_monads.primitives.monad import Monad, NewValueType, ValueType
 
+ErrorType = TypeVar('ErrorType')
+
 
-class Either(Monad[ValueType]):
+# That's the most ugly part.
+# We need to express `Either` with two type parameters and
+# Left and Right with just one parameter.
+# And that's how we do it. Any other and more cleaner ways are appreciated.
+class Either(Generic[ValueType, ErrorType], metaclass=ABCMeta):
     """
     Represents a calculation that may either fail or succeed.
 
     An alternative to using exceptions.
     'Either' (or its alias 'Result') is an abstract type and should not
     be instantiated directly. Instead use 'Right' (or its alias 'Success')
-    and 'Left' (or its alias 'Failure')
+    and 'Left' (or its alias 'Failure').
     """
 
+    _inner_value: Union[ValueType, ErrorType]
 
-class Left(Either[ValueType]):
+    @abstractmethod
+    def unwrap(self) -> ValueType:  # pragma: no cover
+        """
+        Custom magic method to unwrap inner value from monad.
+
+        Should be redefined for ones that actually have values.
+        And for ones that raise an exception for no values.
+        """
+        raise NotImplementedError()
+
+
+@final
+class Left(Either[Any, ErrorType], Monad[ErrorType]):
     """
     Represents a calculation which has failed.
 
     It should contain an error code or message.
     To help with readability you may alternatively use the alias 'Failure'.
     """
 
-    def fmap(self, function) -> 'Left[ValueType]':
+    def __init__(self, inner_value: ErrorType) -> None:
+        """
+        Wraps the given value in the Container.
+
+        'value' is any arbitrary value of any type including functions.
+        """
+        self._inner_value = inner_value
+
+    def fmap(self, function) -> 'Left[ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
         return Left(self._inner_value)
 
-    def bind(self, function) -> 'Left[ValueType]':
+    def bind(self, function) -> 'Left[ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
         return Left(self._inner_value)
 
     def value_or(self, default_value: NewValueType) -> NewValueType:
         """Returns the value if we deal with 'Right' or default if 'Left'."""
         return default_value
 
+    def unwrap(self) -> NoReturn:
+        """Raises an exception, since it does not have a value inside."""
+        raise UnwrapFailedError(self)
+
 
-class Right(Either[ValueType]):
+@final
+class Right(Either[ValueType, Any], Monad[ValueType]):
     """
     Represents a calculation which has succeeded and contains the result.
 
     To help with readability you may alternatively use the alias 'Success'.
     """
 
+    def __init__(self, inner_value: ValueType) -> None:
+        """
+        Wraps the given value in the Container.
+
+        'value' is any arbitrary value of any type including functions.
+        """
+        self._inner_value = inner_value
+
     def fmap(
         self,
         function: Callable[[ValueType], NewValueType],
@@ -60,8 +104,8 @@ def fmap(
 
     def bind(
         self,
-        function: Callable[[ValueType], Either[NewValueType]],
-    ) -> Either[NewValueType]:
+        function: Callable[[ValueType], Either[NewValueType, ErrorType]],
+    ) -> Either[NewValueType, ErrorType]:
         """
         Applies 'function' to the result of a previous calculation.
 
@@ -74,6 +118,10 @@ def value_or(self, default_value: NewValueType) -> ValueType:
         """Returns the value if we deal with 'Right' or default if 'Left'."""
         return self._inner_value
 
+    def unwrap(self) -> ValueType:
+        """Returns the unwrapped value from the inside of this monad."""
+        return self._inner_value
+
 
 # Useful aliases for end users:
 

dry_monads/primitives/exceptions.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from dry_monads.primitives.types import MonadType  # noqa: Z435, F401
+
+
+class UnwrapFailedError(Exception):
+    """Raised when a monad can not be unwrapped into a meaningful value."""
+
+    def __init__(self, monad: 'MonadType') -> None:
+        """
+        Saves halted monad in the inner state.
+
+        So, this monad can later be unpacked from this exception
+        and used as a regular value.
+        """
+        super().__init__()
+        self.halted_monad = monad

dry_monads/primitives/monad.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 from abc import ABCMeta, abstractmethod
-from typing import Generic, TypeVar
+from typing import Any, Generic, TypeVar
 
 ValueType = TypeVar('ValueType')
 NewValueType = TypeVar('NewValueType')
@@ -19,15 +19,7 @@ class Monad(Generic[ValueType], metaclass=ABCMeta):
 
     """
 
-    _inner_value: ValueType
-
-    def __init__(self, inner_value: ValueType) -> None:
-        """
-        Wraps the given value in the Container.
-
-        'value' is any arbitrary value of any type including functions.
-        """
-        self._inner_value = inner_value
+    _inner_value: Any
 
     @abstractmethod
     def fmap(self, function):  # pragma: no cover
@@ -36,7 +28,7 @@ def fmap(self, function):  # pragma: no cover
 
         And returns a new functor value.
         """
-        raise NotImplementedError
+        raise NotImplementedError()
 
     @abstractmethod
     def bind(self, function):  # pragma: no cover
@@ -45,12 +37,22 @@ def bind(self, function):  # pragma: no cover
 
         And returns a new monad.
         """
-        raise NotImplementedError
+        raise NotImplementedError()
 
     @abstractmethod
-    def value_of(self, default_value):
+    def value_or(self, default_value):  # pragma: no cover
         """Forces to unwrap value from monad or return a default."""
-        raise NotImplementedError
+        raise NotImplementedError()
+
+    @abstractmethod
+    def unwrap(self) -> ValueType:  # pragma: no cover
+        """
+        Custom magic method to unwrap inner value from monad.
+
+        Should be redefined for ones that actually have values.
+        And for ones that raise an exception for no values.
+        """
+        raise NotImplementedError()
 
     def __str__(self) -> str:
         """Converts to string."""

dry_monads/primitives/types.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+from typing import TYPE_CHECKING, TypeVar, Union
+
+if TYPE_CHECKING:  # pragma: no cover
+    from dry_monads.either import Either  # noqa: Z435, F401
+    from dry_monads.primitives.monad import Monad  # noqa: Z435, F401
+
+# We need to have this ugly type because there is no other way around it:
+MonadType = TypeVar('MonadType', bound=Union['Monad', 'Either'])

poetry.lock

@@ -6,11 +6,11 @@ authors = ["sobolevn <mail@sobolevn.me>"]
 license = "MIT"
 
 [tool.poetry.dependencies]
-python = "^3.6"
+python = "^3.6 || ^3.7"
+typing-extensions = "^3.7"
 
 [tool.poetry.dev-dependencies]
 mypy = "^0.660.0"
-typing-extensions = "^3.7"
 attrs = "^18.2"
 wemake-python-styleguide = "^0.7.0"
 flake8-pytest = "^1.3"

pyproject.toml

@@ -63,9 +63,12 @@ line_length = 79
 # The mypy configurations: http://bit.ly/2zEl9WI
 python_version = 3.6
 
+# We have disabled this checks due to some problems with `mypy` type
+# system, it does not look like it will be fixed soon.
+# disallow_any_explicit = True
+# disallow_any_generics = True
+
 check_untyped_defs = True
-disallow_any_explicit = True
-disallow_any_generics = True
 disallow_untyped_calls = True
 ignore_errors = False
 ignore_missing_imports = True

setup.cfg

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+from dry_monads.do_notation import do_notation
+from dry_monads.either import Either, Failure, Success
+
+
+@do_notation
+def _example1(number: int) -> Either[int, str]:
+    first = Success(1).unwrap()
+    second = Success(number).unwrap() if number else Failure('E').unwrap()
+    return Success(first + second)
+
+
+@do_notation
+def _example2(number: int) -> Success[int]:
+    first: int = Success(1).unwrap()
+    return Success(first + Failure(number).unwrap())
+
+
+def test_do_notation_success():
+    """Ensures that do notation works well for Success."""
+    assert _example1(5) == Success(6)
+
+
+def test_do_notation_failure():
+    """Ensures that do notation works well for Failure."""
+    assert _example1(0) == Failure('E')
+    assert _example2(0) == Failure(0)