Adds Maybe monad

Author: sobolevn

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 We follow Semantic Versions since the `0.1.0` release.
 
+## Version 0.2.0
+
+### Features
+
+- Adds `Maybe` monad
+- Adds immutability and `__slots__` to all monads
+- Adds `__hash__` support for immutable inner values
+- Adds methods to work with failures
+- Adds `safe` decorator to convert exceptions to `Either` monad
+- Adds `is_successful()` function to detect if your result is a success
+
+### Bugfixes
+
+- Changes the type of `.bind` method for `Success` monad
+
+### Misc
+
+- Improves docs
+
 
 ## Version 0.1.1
 

README.md

@@ -1,6 +1,6 @@
 # dry-monads
 
-[![wemake.services](https://img.shields.io/badge/%20-wemake.services-green.svg?label=%20&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC%2FxhBQAAAAFzUkdCAK7OHOkAAAAbUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP%2F%2F%2F5TvxDIAAAAIdFJOUwAjRA8xXANAL%2Bv0SAAAADNJREFUGNNjYCAIOJjRBdBFWMkVQeGzcHAwksJnAPPZGOGAASzPzAEHEGVsLExQwE7YswCb7AFZSF3bbAAAAABJRU5ErkJggg%3D%3D)](https://wemake.services) [![Build Status](https://travis-ci.org/sobolevn/dry-monads.svg?branch=master)](https://travis-ci.org/sobolevn/dry-monads) [![Coverage Status](https://coveralls.io/repos/github/sobolevn/dry-monads/badge.svg?branch=master)](https://coveralls.io/github/sobolevn/dry-monads?branch=master) [![Documentation Status](https://readthedocs.org/projects/dry-monads/badge/?version=latest)](https://dry-monads.readthedocs.io/en/latest/?badge=latest) [![Python Version](https://img.shields.io/pypi/pyversions/dry-monads.svg)](https://pypi.org/project/dry-monads/) [![Dependencies Status](https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen.svg)](https://github.com/sobolevn/dry-monads/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot) [![dry-monads](https://img.shields.io/badge/style-wemake-000000.svg)](https://github.com/sobolevn/dry-monads)
+[![wemake.services](https://img.shields.io/badge/%20-wemake.services-green.svg?label=%20&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC%2FxhBQAAAAFzUkdCAK7OHOkAAAAbUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP%2F%2F%2F5TvxDIAAAAIdFJOUwAjRA8xXANAL%2Bv0SAAAADNJREFUGNNjYCAIOJjRBdBFWMkVQeGzcHAwksJnAPPZGOGAASzPzAEHEGVsLExQwE7YswCb7AFZSF3bbAAAAABJRU5ErkJggg%3D%3D)](https://wemake.services) [![Build Status](https://travis-ci.org/sobolevn/dry-monads.svg?branch=master)](https://travis-ci.org/sobolevn/dry-monads) [![Coverage Status](https://coveralls.io/repos/github/sobolevn/dry-monads/badge.svg?branch=master)](https://coveralls.io/github/sobolevn/dry-monads?branch=master) [![Documentation Status](https://readthedocs.org/projects/dry-monads/badge/?version=latest)](https://dry-monads.readthedocs.io/en/latest/?badge=latest) [![Python Version](https://img.shields.io/pypi/pyversions/dry-monads.svg)](https://pypi.org/project/dry-monads/)[![dry-monads](https://img.shields.io/badge/style-wemake-000000.svg)](https://github.com/sobolevn/dry-monads)
 
 
 Monads for `python` made simple and safe.
@@ -27,13 +27,13 @@ pip install dry-monads
 We have several the most iconic monads inside:
 
 - [Result, Failure, and Success](https://dry-monads.readthedocs.io/en/latest/pages/either.html) (also known as `Either`, `Left`, and `Right`)
-- `Maybe`, `Some`, and `Nothing` (currently WIP)
-- `Just` (currently WIP)
+- [Maybe, Some, and Nothing](https://dry-monads.readthedocs.io/en/latest/pages/maybe.html)
 
 We also care about code readability and developer experience,
 so we have included some useful features to make your life easier:
 
 - [Do notation](https://dry-monads.readthedocs.io/en/latest/pages/do-notation.html)
+- [Helper functions](https://dry-monads.readthedocs.io/en/latest/pages/functions.html)
 
 
 ## Example

docs/index.rst

@@ -8,8 +8,10 @@ Contents
   :caption: Userguide
 
   pages/monad.rst
+  pages/maybe.rst
   pages/either.rst
   pages/do-notation.rst
+  pages/functions.rst
 
 .. toctree::
   :maxdepth: 1

docs/pages/do-notation.rst

@@ -129,6 +129,38 @@ And at the same time the produced code is simple and readable.
 
 And that's it!
 
+See also:
+  - https://dry-rb.org/gems/dry-monads/do-notation/
+  - https://en.wikibooks.org/wiki/Haskell/do_notation
+  - https://wiki.haskell.org/Do_notation_considered_harmful
+
+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 dry_monads.do_notation import do_notation
+  from dry_monads.either import Success
+
+  @do_notation
+  def function(param: int) -> Success[int]:
+      return Success(param)
+
+  reveal_type(function)
+  # Actual => def (*Any, **Any) -> dry_monads.either.Right*[builtins.int]
+  # Expected => def (int) -> dry_monads.either.Right*[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/Parquery/icontract
+- https://github.com/orsinium/deal
+- https://github.com/deadpixi/contracts
+
 API Reference
 -------------
 

docs/pages/either.rst

@@ -3,8 +3,9 @@ Either
 
 Also known as ``Result``.
 
-What is ``Result``? It is obviously a result of series of computations.
-It might return an error with some extra details.
+``Result`` is obviously a result of some series of computations.
+It might succeed with some resulting value.
+Or it might return an error with some extra details.
 
 ``Result`` consist of two types: ``Success`` and ``Failure``.
 ``Success`` represents successful operation result
@@ -26,7 +27,7 @@ and ``Failure`` indicates that something has failed.
   user_search_result = find_user(0)  # id 0 does not exist!
   # => Failure('User was not found')
 
-When it is useful?
+When is it useful?
 When you do not want to use exceptions to break your execution scope.
 Or when you do not want to use ``None`` to represent empty values,
 since it will raise ``TypeError`` somewhere

docs/pages/functions.rst

@@ -0,0 +1,52 @@
+Helper functions
+================
+
+We feature several helper functions to make your developer experience better.
+
+is_successful
+-------------
+
+:func:`is_succesful <dry_monads.functions.is_successful>` is used to
+tell whether or not your monad is a success.
+We treat only treat monads that does not throw as a successful ones,
+basically: :class:`Right <dry_monads.either.Right>`
+and :class:`Some <dry_monads.maybe.Some>`.
+
+.. code:: python
+
+  from dry_monads.either import Success, Failure
+  from dry_monads.functions import is_successful
+  from dry_monads.maybe import Some, Nothing
+
+  is_successful(Some(1)) and is_successful(Success(1))
+  # => True
+
+  is_successful(Nothing) or is_successful(Failure('text'))
+  # => False
+
+safe
+----
+
+:func:`safe <dry_monads.functions.safe>` is used to convert
+regular functions that can throw exceptions to functions
+that return :class:`Either <dry_monads.either.Either>` monad.
+
+.. code:: python
+
+  from dry_monads.functions import safe
+
+  @safe
+  def divide(number: int) -> float:
+      return number / number
+
+  divide(1)
+  # => Success(1.0)
+
+  divide(0)
+  # => Failure(ZeroDivisionError)
+
+API Reference
+-------------
+
+.. automodule:: dry_monads.functions
+   :members:

docs/pages/maybe.rst

@@ -0,0 +1,62 @@
+Maybe
+=====
+
+The ``Maybe`` monad is used when a series of computations
+could return ``None`` at any point.
+
+Maybe.new
+---------
+
+``Maybe`` consist of two types: ``Some`` and ``Nothing``.
+We have a convenient method to create different ``Maybe`` monad types
+based on just a single value:
+
+.. code:: python
+
+  from dry_monads.maybe import Maybe
+
+  Maybe.new(1)
+  # => Some(1)
+
+  Maybe.new(None)
+  # => Nothing()
+
+Usage
+-----
+
+It might be very useful for complex operations like the following one:
+
+.. code:: python
+
+  from dataclasses import dataclass
+  from typing import Optional
+
+  @dataclass
+  class Address(object):
+      street: Optional[str]
+
+  @dataclass
+  class User(object):
+      address: Optional[Address]
+
+  @dataclass
+  class Order(object):
+      user: Optional[User]
+
+  order: Order  # some existing Order instance
+  Maybe.new(order.user).bind(
+    lambda user: Maybe.new(user.address),
+  ).bind(
+    lambda address: Maybe.new(address.street),
+  )
+  # =>
+  # Will return Some('address street info') only when all keys are not None
+  # Otherwise will return Nothing
+
+API Reference
+-------------
+
+.. autoclasstree:: dry_monads.maybe
+
+.. automodule:: dry_monads.maybe
+   :members:

docs/pages/monad.rst

@@ -71,6 +71,11 @@ to use monads with pure functions.
   result = Success(1).fmap(double)
   # => will be equal to Success(2)
 
+Reverse operations
+~~~~~~~~~~~~~~~~~~
+
+TODO: write about ``or_bind`` and ``or_fmap`` values.
+
 Unwrapping values
 ~~~~~~~~~~~~~~~~~
 

dry_monads/do_notation.py

@@ -6,23 +6,17 @@
 from dry_monads.primitives.exceptions import UnwrapFailedError
 from dry_monads.primitives.types import MonadType
 
+# Typing decorators is not an easy task, see:
+# https://github.com/python/mypy/issues/3157
+
 
 def do_notation(
     function: Callable[..., MonadType],
 ) -> Callable[..., MonadType]:
     """
     Decorator to enable 'do-notation' context.
 
-    See example usages below.
-
-    .. code:: python
-
-
-    See also:
-        - https://dry-rb.org/gems/dry-monads/do-notation/
-        - https://en.wikibooks.org/wiki/Haskell/do_notation
-        - https://wiki.haskell.org/Do_notation_considered_harmful
-
+    Should be used for series of computations that rely on ``.unwrap`` method.
     """
     @wraps(function)
     def decorator(*args, **kwargs) -> MonadType:

dry_monads/either.py

@@ -7,6 +7,7 @@
 
 from dry_monads.primitives.exceptions import UnwrapFailedError
 from dry_monads.primitives.monad import Monad, NewValueType, ValueType
+from dry_monads.primitives.types import MonadType
 
 ErrorType = TypeVar('ErrorType')
 
@@ -104,8 +105,8 @@ def fmap(
 
     def bind(
         self,
-        function: Callable[[ValueType], Either[NewValueType, ErrorType]],
-    ) -> Either[NewValueType, ErrorType]:
+        function: Callable[[ValueType], MonadType],
+    ) -> MonadType:
         """
         Applies 'function' to the result of a previous calculation.
 

dry_monads/functions.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+
+from functools import wraps
+from typing import Callable, TypeVar
+
+from dry_monads.either import Either, Failure, Success
+from dry_monads.primitives.exceptions import UnwrapFailedError
+from dry_monads.primitives.types import MonadType
+
+_ReturnType = TypeVar('_ReturnType')
+
+
+def is_successful(monad: MonadType) -> bool:
+    """Determins if a monad was a success or not."""
+    try:
+        monad.unwrap()
+    except UnwrapFailedError:
+        return False
+    else:
+        return True
+
+
+def safe(
+    function: Callable[..., _ReturnType],
+) -> Callable[..., Either[_ReturnType, Exception]]:
+    """
+    Decorator to covert exception throwing function to 'Either' monad.
+
+    Show be used with care, since it only catches 'Exception' subclasses.
+    It does not catch 'BaseException' subclasses.
+    """
+    @wraps(function)
+    def decorator(*args, **kwargs) -> Either[_ReturnType, Exception]:
+        try:
+            return Success(function(*args, **kwargs))
+        except Exception as exc:
+            return Failure(exc)
+    return decorator