Adds ebind and efmap

Author: sobolevn

CHANGELOG.md

@@ -8,14 +8,15 @@ We follow Semantic Versions since the `0.1.0` release.
 
 - 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
+- Changes how equality works, so now `Failure(1) != Success(1)`
+- Changes how new instances created on unused methods
 
 ### Misc
 

docs/pages/monad.rst

@@ -53,7 +53,7 @@ is used to literally bind two different monads together.
       ...
 
   result = Success(1).bind(make_http_call)
-  # => will be equal to either Success[int] or Failure[str]
+  # => 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.
@@ -69,12 +69,46 @@ to use monads with pure functions.
       return state * 2
 
   result = Success(1).fmap(double)
-  # => will be equal to Success(2)
+  # => Will be equal to Success(2)
 
 Reverse operations
 ~~~~~~~~~~~~~~~~~~
 
-TODO: write about ``or_bind`` and ``or_fmap`` values.
+We also support two special methods to work with "failed"
+monads like ``Failure`` and ``Nothing``:
+
+- :func:`Monad.efmap <dry_monads.primitives.monad.Monad.efmap>` the opposite
+  of ``fmap`` method that works only when monad is failed
+- :func:`Monad.ebind <dry_monads.primitives.monad.Monad.ebind>` the opposite
+  of ``bind`` method that works only when monad is failed
+
+.. code:: python
+
+  from dry_monads.either import Failure
+
+  def double(state: int) -> float:
+      return state * 2.0
+
+  Failure(1).efmap(double)
+  # => Will be equal to Success(2.0)
+
+So, ``efmap`` can be used to fix some fixable errors
+during the pipeline execution.
+
+.. code:: python
+
+  from dry_monads.either import Either, Failure, Success
+
+  def fix(state: Exception) -> Either[int, Exception]:
+      if isinstance(state, ZeroDivisionError):
+          return Success(0)
+      return Failure(state)
+
+  Failure(ZeroDivisionError).ebind(fix)
+  # => Will be equal to Success(0)
+
+``ebind`` can return any monad you want.
+It can also be fixed to get your flow on the right track again.
 
 Unwrapping values
 ~~~~~~~~~~~~~~~~~

dry_monads/either.py

@@ -58,11 +58,34 @@ def __init__(self, inner_value: ErrorType) -> None:
 
     def fmap(self, function) -> 'Left[ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
-        return Left(self._inner_value)
+        return self
 
     def bind(self, function) -> 'Left[ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
-        return Left(self._inner_value)
+        return self
+
+    def efmap(
+        self,
+        function: Callable[[ErrorType], NewValueType],
+    ) -> 'Right[NewValueType]':
+        """
+        Applies function to the inner value.
+
+        Applies 'function' to the contents of the 'Right' instance
+        and returns a new 'Right' object containing the result.
+        'function' should accept a single "normal" (non-monad) argument
+        and return a non-monad result.
+        """
+        return Right(function(self._inner_value))
+
+    def ebind(self, function: Callable[[ErrorType], MonadType]) -> MonadType:
+        """
+        Applies 'function' to the result of a previous calculation.
+
+        'function' should accept a single "normal" (non-monad) argument
+        and return either a 'Left' or 'Right' type object.
+        """
+        return function(self._inner_value)
 
     def value_or(self, default_value: NewValueType) -> NewValueType:
         """Returns the value if we deal with 'Right' or default if 'Left'."""
@@ -115,6 +138,14 @@ def bind(
         """
         return function(self._inner_value)
 
+    def efmap(self, function) -> 'Right[ValueType]':
+        """Returns the 'Right' instance that was used to call the method."""
+        return self
+
+    def ebind(self, function) -> 'Right[ValueType]':
+        """Returns the 'Right' instance that was used to call the method."""
+        return self
+
     def value_or(self, default_value: NewValueType) -> ValueType:
         """Returns the value if we deal with 'Right' or default if 'Left'."""
         return self._inner_value

dry_monads/maybe.py

@@ -54,11 +54,37 @@ def __init__(self, inner_value: Literal[None] = None) -> None:
 
     def fmap(self, function) -> 'Nothing':
         """Returns the 'Nothing' instance that was used to call the method."""
-        return Nothing(self._inner_value)
+        return self
 
     def bind(self, function) -> 'Nothing':
         """Returns the 'Nothing' instance that was used to call the method."""
-        return Nothing(self._inner_value)
+        return self
+
+    def efmap(
+        self,
+        function: Callable[[Literal[None]], 'NewValueType'],
+    ) -> 'Some[NewValueType]':
+        """
+        Applies function to the inner value.
+
+        Applies 'function' to the contents of the 'Some' instance
+        and returns a new 'Some' object containing the result.
+        'function' should accept a single "normal" (non-monad) argument
+        and return a non-monad result.
+        """
+        return Some(function(self._inner_value))
+
+    def ebind(
+        self,
+        function: Callable[[Literal[None]], MonadType],
+    ) -> MonadType:
+        """
+        Applies 'function' to the result of a previous calculation.
+
+        'function' should accept a single "normal" (non-monad) argument
+        and return either a 'Nothing' or 'Some' type object.
+        """
+        return function(self._inner_value)
 
     def value_or(self, default_value: NewValueType) -> NewValueType:
         """Returns the value if we deal with 'Some' or default if 'Nothing'."""
@@ -111,6 +137,14 @@ def bind(
         """
         return function(self._inner_value)
 
+    def efmap(self, function) -> 'Some[ValueType]':
+        """Returns the 'Some' instance that was used to call the method."""
+        return self
+
+    def ebind(self, function) -> 'Some[ValueType]':
+        """Returns the 'Some' instance that was used to call the method."""
+        return self
+
     def value_or(self, default_value: NewValueType) -> ValueType:
         """Returns the value if we deal with 'Some' or default if 'Nothing'."""
         return self._inner_value

dry_monads/primitives/monad.py

@@ -34,6 +34,8 @@ def __eq__(self, other) -> bool:
         """Used to compare two 'Monad' objects."""
         if not isinstance(other, _BaseMonad):
             return False
+        if type(self) != type(other):
+            return False
         return self._inner_value == other._inner_value  # noqa: Z441
 
 
@@ -60,6 +62,8 @@ def fmap(self, function):  # pragma: no cover
         Applies 'function' to the contents of the functor.
 
         And returns a new functor value.
+        Works for monads that represent success.
+        Is the opposite of :meth:`~efmap`.
         """
         raise NotImplementedError()
 
@@ -69,6 +73,30 @@ def bind(self, function):  # pragma: no cover
         Applies 'function' to the result of a previous calculation.
 
         And returns a new monad.
+        Works for monads that represent success.
+        Is the opposite of :meth:`~ebind`.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def efmap(self, function):  # pragma: no cover
+        """
+        Applies 'function' to the contents of the functor.
+
+        And returns a new functor value.
+        Works for monads that represent failure.
+        Is the opposite of :meth:`~fmap`.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def ebind(self, function):  # pragma: no cover
+        """
+        Applies 'function' to the result of a previous calculation.
+
+        And returns a new monad.
+        Works for monads that represent failure.
+        Is the opposite of :meth:`~bind`.
         """
         raise NotImplementedError()
 

tests/test_either/test_either_bind.py

@@ -25,3 +25,26 @@ def factory(inner_value: int) -> Left[TypeError]:
 
     assert bound == Left(input_value)
     assert str(bound) == 'Left: 5'
+
+
+def test_ebind_success():
+    """Ensures that ebind works for Right monad."""
+    def factory(inner_value: int) -> Right[int]:
+        return Right(inner_value * 2)
+
+    bound = Right(5).ebind(factory)
+
+    assert bound == Right(5)
+    assert str(bound) == 'Right: 5'
+
+
+def test_ebind_failure():
+    """Ensures that ebind works for Right monad."""
+    def factory(inner_value: int) -> Left[float]:
+        return Left(float(inner_value + 1))
+
+    expected = 6.0
+    bound = Left(5).ebind(factory)
+
+    assert bound == Left(expected)
+    assert str(bound) == 'Left: 6.0'

tests/test_either/test_either_equality.py

@@ -12,11 +12,17 @@ def test_nonequality():
 
     assert Left(input_value) != input_value
     assert Right(input_value) != input_value
+    assert Left(input_value) != Right(input_value)
 
 
 def test_is_compare():
     """Ensures that `is` operator works correctly."""
-    assert Right(1) is not Right(1)
+    left = Left(1)
+    right = Right(1)
+
+    assert left.bind(lambda state: state) is left
+    assert right.ebind(lambda state: state) is right
+    assert right is not Right(1)
 
 
 def test_immutability_failure():

tests/test_either/test_either_fmap.py

@@ -11,3 +11,13 @@ def test_fmap_success():
 def test_fmap_failure():
     """Ensures that left identity works for Right monad."""
     assert Left(5).fmap(str) == Left(5)
+
+
+def test_efmap_success():
+    """Ensures that left identity works for Right monad."""
+    assert Right(5).efmap(str) == Right(5)
+
+
+def test_efmap_failure():
+    """Ensures that left identity works for Right monad."""
+    assert Left(5).efmap(str) == Right('5')

tests/test_maybe/test_maybe_bind.py

@@ -4,7 +4,7 @@
 
 
 def test_bind_some():
-    """Ensures that Nothing identity works for Some monad."""
+    """Ensures that left identity works for Some monad."""
     def factory(inner_value: int) -> Some[int]:
         return Some(inner_value * 2)
 
@@ -16,11 +16,33 @@ def factory(inner_value: int) -> Some[int]:
 
 
 def test_bind_nothing():
-    """Ensures that Nothing identity works for Some monad."""
+    """Ensures that left identity works for Some monad."""
     def factory(inner_value: None) -> Some[int]:
         return Some(1)
 
     bound = Nothing().bind(factory)
 
     assert bound == Nothing(None)
     assert str(bound) == 'Nothing: None'
+
+
+def test_ebind_some():
+    """Ensures that left identity works for Some monad."""
+    def factory(inner_value: int) -> Some[int]:
+        return Some(inner_value * 2)
+
+    bound = Some(5).ebind(factory)
+
+    assert bound == Some(5)
+    assert str(bound) == 'Some: 5'
+
+
+def test_ebind_nothing():
+    """Ensures that left identity works for Some monad."""
+    def factory(inner_value: None) -> Some[int]:
+        return Some(1)
+
+    bound = Nothing().ebind(factory)
+
+    assert bound == Some(1)
+    assert str(bound) == 'Some: 1'

tests/test_maybe/test_maybe_equality.py

@@ -11,11 +11,17 @@ def test_nonequality():
     assert Nothing() is not None
     assert Nothing(None) is not None
     assert Some(5) != 5
+    assert Some(None) != Nothing()
 
 
 def test_is_compare():
     """Ensures that `is` operator works correctly."""
-    assert Some(1) is not Some(1)
+    nothing = Nothing()
+    some_monad = Some(1)
+
+    assert nothing.bind(lambda state: state) is nothing
+    assert some_monad.ebind(lambda state: state) is some_monad
+    assert some_monad is not Some(1)
 
 
 def test_immutability_failure():

tests/test_maybe/test_maybe_fmap.py

@@ -11,3 +11,13 @@ def test_fmap_some():
 def test_fmap_nothing():
     """Ensures that fmap works for Nothing monad."""
     assert Nothing().fmap(str) == Nothing(None)
+
+
+def test_efmap_some():
+    """Ensures that efmap works for Some monad."""
+    assert Some(5).efmap(str) == Some(5)
+
+
+def test_efmap_nothing():
+    """Ensures that efmap works for Nothing monad."""
+    assert Nothing().efmap(lambda state: str(state)) == Some('None')