Closes #238, closes #236

Author: sobolevn

CHANGELOG.md

@@ -13,6 +13,8 @@ See (0Ver)[https://0ver.org/].
 - **Breaking**: renames `join` to `flatten`, sorry!
 - **Breaking**: renames `box` to `bind` and moves it to `returns.pointfree`
 - **Breaking**: renames `coalesce` to `fold`
+- **Breaking**: removes `Maybe.rescue` and `Maybe.fix` methods
+- Adds `rescue` pointfree method
 - Adds `Result.lift`, `Maybe.lift`, and `RequiresContext.lift` functions
   in addition to `IO.lift`
 - Adds `RequiresContext` container and `Context` helper class

docs/pages/maybe.rst

@@ -129,6 +129,37 @@ and converts it to return ``Maybe`` instead:
   '<Some: 1>'
 
 
+FAQ
+---
+
+How can I turn Maybe into Optional again?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When working with regular Python,
+you might need regular ``Optional[a]`` values.
+
+You can easily get one from your ``Maybe`` container at any point in time:
+
+.. code:: python
+
+  >>> from returns.maybe import Maybe
+  >>> assert Maybe.new(1).value_or(None) == 1
+  >>> assert Maybe.new(None).value_or(None) is None
+
+As you can see, revealed type of ``.value_or(None)`` is ``Optional[a]``.
+Use it a fallback.
+
+Why there's no IOMaybe?
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We do have ``IOResult``, but we don't have ``IOMaybe``. Why?
+Because when dealing with ``IO`` there are a lot of possible errors.
+And ``Maybe`` represents just ``None`` and the value.
+
+It is not useful for ``IO`` related tasks.
+So, use ``Result`` instead, which can represent what happened to your ``IO``.
+
+
 Further reading
 ---------------
 

returns/_generated/fold.py

@@ -77,8 +77,8 @@ def decorator(container):
 
 _fold_ioresult: Callable[
     [
-        Callable[[_ValueType], IO[_FirstType]],
-        Callable[[_ErrorType], IO[_FirstType]],
+        Callable[[IO[_ValueType]], IO[_FirstType]],
+        Callable[[IO[_ErrorType]], IO[_FirstType]],
     ],
     Callable[[IOResult[_ValueType, _ErrorType]], IO[_FirstType]],
 ] = _fold

returns/_generated/pointfree/bind.py

@@ -8,18 +8,23 @@ def _bind(function):
     In other words, it modifies the function
     signature from: ``a -> Container[b]`` to: ``Container[a] -> Container[b]``
 
+    Similar to :func:`returns.pointfree.rescue`,
+    but works for successful containers.
+
     This is how it should be used:
 
     .. code:: python
 
       >>> from returns.pointfree import bind
-      >>> from returns.maybe import Maybe, Some
+      >>> from returns.maybe import Maybe, Some, Nothing
 
       >>> def example(argument: int) -> Maybe[int]:
       ...     return Some(argument + 1)
       ...
-      >>> bind(example)(Some(1)) == Some(2)
-      True
+      >>> assert bind(example)(Some(1)) == Some(2)
+      >>> assert bind(example)(Nothing) == Nothing
+
+    Note, that this function works for all containers with ``.bind`` method.
 
     """
     return lambda container: container.bind(function)

returns/_generated/pointfree/bind.pyi

@@ -13,7 +13,7 @@ _NewValueType = TypeVar('_NewValueType')
 _EnvType = TypeVar('_EnvType')
 
 
-# Box:
+# Bind:
 
 @overload
 def _bind(

returns/_generated/pointfree/rescue.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+
+def _rescue(function):
+    """
+    Boxes function's input parameter from a regular value to a container.
+
+    In other words, it modifies the function
+    signature from: ``a -> Container[b]`` to: ``Container[a] -> Container[b]``
+
+    Similar to :func:`returns.pointfree.bind`, but works for failed containers.
+
+    This is how it should be used:
+
+    .. code:: python
+
+      >>> from returns.pointfree import rescue
+      >>> from returns.result import Success, Failure, Result
+
+      >>> def example(argument: int) -> Result[str, int]:
+      ...     return Success(argument + 1)
+      ...
+      >>> assert rescue(example)(Success('a')) == Success('a')
+      >>> assert rescue(example)(Failure(1)) == Success(2)
+
+    Note, that this function works for all containers with ``.bind`` method.
+
+    """
+    return lambda container: container.rescue(function)

returns/_generated/pointfree/rescue.pyi

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, TypeVar, overload
+
+from returns.io import IOResult
+from returns.result import Result
+
+_ValueType = TypeVar('_ValueType')
+_ErrorType = TypeVar('_ErrorType')
+_NewValueType = TypeVar('_NewValueType')
+_NewErrorType = TypeVar('_NewErrorType')
+
+
+@overload
+def _rescue(
+    function: Callable[[_ErrorType], Result[_ValueType, _NewErrorType]],
+) -> Callable[
+    [Result[_ValueType, _ErrorType]],
+    Result[_ValueType, _NewErrorType],
+]:
+    ...
+
+
+@overload
+def _rescue(
+    function: Callable[[_ErrorType], IOResult[_ValueType, _NewErrorType]],
+) -> Callable[
+    [IOResult[_ValueType, _ErrorType]],
+    IOResult[_ValueType, _NewErrorType],
+]:
+    ...

returns/io.py

@@ -367,6 +367,21 @@ def fix(
         """
         return self.from_result(self._inner_value.fix(function))
 
+    def alt(
+        self,
+        function: Callable[[_ErrorType], _NewErrorType],
+    ) -> 'IOResult[_ValueType, _NewErrorType]':
+        """
+        Composes failed container with a pure function to modify failure.
+
+        .. code:: python
+
+          >>> from returns.io import IOFailure
+          >>> assert IOFailure(1).alt(float) == IOFailure(1.0)
+
+        """
+        return self.from_result(self._inner_value.alt(function))
+
     def rescue(
         self,
         function: Callable[
@@ -392,21 +407,6 @@ def rescue(
         """
         raise NotImplementedError
 
-    def alt(
-        self,
-        function: Callable[[_ErrorType], _NewErrorType],
-    ) -> 'IOResult[_ValueType, _NewErrorType]':
-        """
-        Composes failed container with a pure function to modify failure.
-
-        .. code:: python
-
-          >>> from returns.io import IOFailure
-          >>> assert IOFailure(1).alt(float) == IOFailure(1.0)
-
-        """
-        return self.from_result(self._inner_value.alt(function))
-
     def value_or(
         self,
         default_value: _NewValueType,

returns/maybe.py

@@ -108,44 +108,6 @@ def bind(
         """
         raise NotImplementedError
 
-    def fix(
-        self,
-        function: Callable[[None], Optional[_NewValueType]],
-    ) -> 'Maybe[_NewValueType]':
-        """
-        Composes failed container with a pure function to fix the failure.
-
-        .. code:: python
-
-          >>> from returns.maybe import Nothing, Some
-          >>> def fixable(_state) -> str:
-          ...      return 'ab'
-          ...
-          >>> assert Some('a').fix(fixable) == Some('a')
-          >>> assert Nothing.fix(fixable) == Some('ab')
-
-        """
-        raise NotImplementedError
-
-    def rescue(
-        self,
-        function: Callable[[None], 'Maybe[_NewValueType]'],
-    ) -> 'Maybe[_NewValueType]':
-        """
-        Composes failed container with a function that returns a container.
-
-        .. code:: python
-
-          >>> from returns.maybe import Nothing, Maybe, Some
-          >>> def rescuable(_state) -> Maybe[str]:
-          ...      return Some('ab')
-          ...
-          >>> assert Some('a').rescue(rescuable) == Some('a')
-          >>> assert Nothing.rescue(rescuable) == Some('ab')
-
-        """
-        raise NotImplementedError
-
     def value_or(
         self,
         default_value: _NewValueType,
@@ -262,14 +224,6 @@ def bind(self, function):
         """Does nothing for ``Nothing``."""
         return self
 
-    def fix(self, function):
-        """Composes pure function with a failed container."""
-        return Maybe.new(function(self._inner_value))
-
-    def rescue(self, function):
-        """Composes failed container with a function that returns container."""
-        return function(self._inner_value)
-
     def value_or(self, default_value):
         """Returns default value."""
         return default_value
@@ -310,14 +264,6 @@ def bind(self, function):
         """Binds current container to a function that returns container."""
         return function(self._inner_value)
 
-    def fix(self, function):
-        """Does nothing."""
-        return self
-
-    def rescue(self, function):
-        """Does nothing."""
-        return self
-
     def value_or(self, default_value):
         """Returns inner value for successful container."""
         return self._inner_value

returns/pointfree.py

@@ -1,3 +1,4 @@
 # -*- coding: utf-8 -*-
 
 from returns._generated.pointfree.bind import _bind as bind  # noqa: F401
+from returns._generated.pointfree.rescue import _rescue as rescue  # noqa: F401