Adds .failure() method

Author: sobolevn

CHANGELOG.md

@@ -11,6 +11,7 @@ We follow Semantic Versions since the `0.1.0` release.
 - 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
+- Adds `failure()` method to unwrap values from failed monads
 
 ### Bugfixes
 

docs/pages/monad.rst

@@ -139,6 +139,21 @@ inner state of monads into a regular types:
 
 The most user-friendly way to use ``unwrap`` method is with :ref:`do-notation`.
 
+For failing monads you can
+use :func:`Monad.failure <dry_monads.primitives.monad.Monad.failure>`
+to unwrap failed state:
+
+.. code:: python
+
+  Failure(1).failure()
+  # => 1
+
+  Success(1).failure()
+  # => Traceback (most recent call last): UnwrapFailedError
+
+Be careful, since this method will raise an exception
+when you try to ``failure`` a successful monad.
+
 Immutability
 ------------
 

dry_monads/either.py

@@ -95,6 +95,10 @@ def unwrap(self) -> NoReturn:
         """Raises an exception, since it does not have a value inside."""
         raise UnwrapFailedError(self)
 
+    def failure(self) -> ErrorType:
+        """Unwraps inner error value from failed monad."""
+        return self._inner_value
+
 
 @final
 class Right(Either[ValueType, Any], Monad[ValueType]):
@@ -154,6 +158,10 @@ def unwrap(self) -> ValueType:
         """Returns the unwrapped value from the inside of this monad."""
         return self._inner_value
 
+    def failure(self) -> NoReturn:
+        """Raises an exception, since it does not have an error inside."""
+        raise UnwrapFailedError(self)
+
 
 # Useful aliases for end users:
 

dry_monads/maybe.py

@@ -94,6 +94,10 @@ def unwrap(self) -> NoReturn:
         """Raises an exception, since it does not have a value inside."""
         raise UnwrapFailedError(self)
 
+    def failure(self) -> None:
+        """Unwraps inner error value from failed monad."""
+        return self._inner_value
+
 
 @final
 class Some(Maybe[ValueType]):
@@ -152,3 +156,7 @@ def value_or(self, default_value: NewValueType) -> ValueType:
     def unwrap(self) -> ValueType:
         """Returns the unwrapped value from the inside of this monad."""
         return self._inner_value
+
+    def failure(self) -> NoReturn:
+        """Raises an exception, since it does not have an error inside."""
+        raise UnwrapFailedError(self)

dry_monads/primitives/monad.py

@@ -112,5 +112,16 @@ def unwrap(self) -> ValueType:  # pragma: no cover
 
         Should be redefined for ones that actually have values.
         And for ones that raise an exception for no values.
+
+        This method is the opposite of :meth:`~failure`.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def failure(self):  # pragma: no cover
+        """
+        Custom magic method to unwrap inner value from the failed monad.
+
+        This method is the opposite of :meth:`~unwrap`.
         """
         raise NotImplementedError()

setup.cfg

@@ -19,6 +19,9 @@ doctests = True
 enable-extensions = G
 isort-show-traceback = True
 
+# wemake-python-styleguide
+max-methods = 8
+
 per-file-ignores =
   # Disable some pydocstyle checks for package:
   dry_monads/**/*.py: D104

tests/test_either/test_either_failure.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from dry_monads.either import Left, Right
+from dry_monads.primitives.exceptions import UnwrapFailedError
+
+
+def test_unwrap_success():
+    """Ensures that unwrap works for Right monad."""
+    with pytest.raises(UnwrapFailedError):
+        assert Right(5).failure()
+
+
+def test_unwrap_failure():
+    """Ensures that unwrap works for Left monad."""
+    assert Left(5).failure() == 5

tests/test_maybe/test_maybe_failure.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from dry_monads.maybe import Nothing, Some
+from dry_monads.primitives.exceptions import UnwrapFailedError
+
+
+def test_unwrap_success():
+    """Ensures that unwrap works for Some monad."""
+    with pytest.raises(UnwrapFailedError):
+        assert Some(1).failure()
+
+
+def test_unwrap_failure():
+    """Ensures that unwrap works for Nothing monad."""
+    assert Nothing().failure() is None  # type: ignore