Closes #253, closes #251, closes #249

Author: sobolevn

CHANGELOG.md

@@ -12,7 +12,6 @@ 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 function
@@ -33,7 +32,7 @@ See [0Ver](https://0ver.org/).
 - Adds `IOResult` support for `bind`
 - Adds `IOResult` support for `flatten`
 - Adds `IOResult` support for `@pipeline`
-- Adds `IOResult` support for `fold`
+- Adds `IOResult` support for `coalesce`
 - Adds `IOResult` support for `is_successful`
 
 - Adds `RequiresContextIOResult` container
@@ -45,6 +44,8 @@ See [0Ver](https://0ver.org/).
 - Adds `Result.lift`, `Maybe.lift`, `RequiresContext.lift`,
   and `RequiresContextResult.lift` functions in addition to `IO.lift`
 - Adds `Immutable` primitive type
+- Adds `Unitable` protocol and `.from_success()` and `.from_failure()`
+  methods for all `Result` realted classes
 
 
 ### Bugfixes

docs/pages/container.rst

@@ -101,6 +101,10 @@ Note::
 
   All containers support these methods.
 
+You can read more about methods
+that some other containers support
+and :ref:`interfaces <base-interfaces>` behind them.
+
 
 .. _immutability:
 
@@ -117,6 +121,9 @@ since we are using ``__slots__`` for better performance and strictness.
 
 Well, nothing is **really** immutable in python, but you were warned.
 
+We also provide :class:`returns.primitives.types.Immutable` mixin
+that users can use to quickly make their classes immutable.
+
 
 .. _type-safety:
 
@@ -217,10 +224,24 @@ Further reading
 - :ref:`Railway oriented programming <railway>`
 
 
+.. _base-interfaces:
+
 API Reference
 -------------
 
+``BaseContainer`` is a base class for all other container.
+It defines some basic things like representation, hashing, pickling, etc.
+
 .. autoclasstree:: returns.primitives.container
 
 .. automodule:: returns.primitives.container
    :members:
+   :special-members:
+
+Here are our interfaces (or protocols to be more specific)
+that we use inside our app:
+
+.. autoclasstree:: returns.primitives.interfaces
+
+.. automodule:: returns.primitives.interfaces
+   :members:

docs/pages/result.rst

@@ -98,7 +98,12 @@ FAQ
 How to create unit objects?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use ``Success`` or ``Failure`` together with the explicit annotation.
+Use ``Success`` or ``Failure``.
+Alternatively :meth:`retunrs.result.Result.from_success`
+or :meth:`retunrs.result.Result.from_failure`.
+
+It might be a good idea to use unit functions
+together with the explicit annotation.
 Python's type system does not allow us to do much, so this is required:
 
 .. code:: python
@@ -112,18 +117,8 @@ Python's type system does not allow us to do much, so this is required:
   >>> str(first.bind(callback))
   '<Success: 1.0>'
 
-Otherwise it would raise a ``mypy`` error:
-
-.. code:: python
-
-  first = Success(1)
-  first.bind(callback)
-  # Argument 1 to "bind" of "Result" has incompatible type
-  # "Callable[[int], Result[float, int]]";
-  # expected "Callable[[int], Result[float, NoReturn]]"
-
-This happens because ``mypy`` is unable to implicitly
-cast ``NoReturn`` to any other type.
+Otherwise ``first`` will have ``Result[int, Any]`` type.
+Which is okay in some situations.
 
 What is the difference between ``Success`` and ``_Success``?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

returns/context/requires_context_io_result.py

@@ -70,8 +70,12 @@ class RequiresContextIOResult(
 
     - raw values and pure functions
     - ``RequiresContext`` values and pure functions returning it
-    - ``Result`` and functions returning it
+    - ``RequiresContextResult`` values and pure functions returning it
+    - ``Result`` and pure functions returning it
     - ``IOResult`` and functions returning it
+    - other ``RequiresContextIOResult`` related functions and values
+
+    This is a complex type for complex tasks!
 
     Imporatant implementation detail:
     due it is meaning, ``RequiresContextIOResult``
@@ -868,6 +872,33 @@ def from_failed_context(
             lambda deps: IOFailure(inner_value(deps)),
         )
 
+    @classmethod
+    def from_result_context(
+        cls, inner_value: RequiresContextResult[
+            _EnvType, _ValueType, _ErrorType,
+        ],
+    ) -> 'RequiresContextIOResult[_EnvType, _ValueType, _ErrorType]':
+        """
+        Creates new container from ``RequiresContextResult`` as a unit value.
+
+        .. code:: python
+
+          >>> from returns.context import RequiresContextResult
+          >>> from returns.io import IOSuccess, IOFailure
+
+          >>> assert RequiresContextIOResult.from_result_context(
+          ...     RequiresContextResult.from_success(1),
+          ... )(...) == IOSuccess(1)
+
+          >>> assert RequiresContextIOResult.from_result_context(
+          ...     RequiresContextResult.from_failure(1),
+          ... )(...) == IOFailure(1)
+
+        """
+        return RequiresContextIOResult(
+            lambda deps: IOResult.from_result(inner_value(deps)),
+        )
+
     @classmethod
     def from_success(
         cls, inner_value: _FirstType,

returns/io.py

@@ -600,6 +600,48 @@ def from_result(
             return _IOSuccess(container)
         return _IOFailure(container)
 
+    @classmethod
+    def from_success(
+        cls, inner_value: _NewValueType,
+    ) -> 'IOResult[_NewValueType, Any]':
+        """
+        One more value to create success unit values.
+
+        This is a part of :class:`returns.primitives.interfaces.Unitable`.
+        It is useful as a united way to create a new value from any container.
+
+        .. code:: python
+
+          >>> from returns.io import IOResult, IOSuccess
+          >>> assert IOResult.from_success(1) == IOSuccess(1)
+
+        You can use this method or :func:`~IOSuccess`,
+        choose the most convenient for you.
+
+        """
+        return IOSuccess(inner_value)
+
+    @classmethod
+    def from_failure(
+        cls, inner_value: _NewErrorType,
+    ) -> 'IOResult[Any, _NewErrorType]':
+        """
+        One more value to create failred unit values.
+
+        This is a part of :class:`returns.primitives.interfaces.Unitable`.
+        It is useful as a united way to create a new value from any container.
+
+        .. code:: python
+
+          >>> from returns.io import IOResult, IOFailure
+          >>> assert IOResult.from_failure(1) == IOFailure(1)
+
+        You can use this method or :func:`~IOFailure`,
+        choose the most convenient for you.
+
+        """
+        return IOFailure(inner_value)
+
     def __str__(self) -> str:
         """Custom ``str`` representation for better readability."""
         return '<IOResult: {0}>'.format(self._inner_value)

returns/primitives/container.py

@@ -1,9 +1,7 @@
 # -*- coding: utf-8 -*-
 
 from abc import ABCMeta
-from typing import Any, Callable, TypeVar, Union
-
-from typing_extensions import Protocol, runtime
+from typing import Any, TypeVar
 
 from returns.primitives.types import Immutable
 
@@ -51,129 +49,3 @@ def __getstate__(self) -> Any:
     def __setstate__(self, state: Any) -> None:
         """Loading state from pickled data."""
         object.__setattr__(self, '_inner_value', state)  # noqa: WPS609
-
-
-@runtime
-class Bindable(Protocol[_ValueType]):
-    """
-    Represents a "context" in which calculations can be executed.
-
-    ``Bindable`` allows you to bind together
-    a series of calculations while maintaining
-    the context of that specific container.
-    """
-
-    def bind(
-        self, function: Callable[[_ValueType], 'Bindable[_NewValueType]'],
-    ) -> 'Bindable[_NewValueType]':
-        """
-        Applies 'function' to the result of a previous calculation.
-
-        And returns a new container.
-        Works for containers that represent success.
-        Is the opposite of :meth:`Rescueable.rescue`.
-        """
-
-
-@runtime
-class Mappable(Protocol[_ValueType]):
-    """
-    Allows to chain wrapped values with regular functions.
-
-    Behaves like functor.
-    """
-
-    def map(  # noqa: A003
-        self, function: Callable[[_ValueType], _NewValueType],
-    ) -> 'Mappable[_NewValueType]':
-        """
-        Applies 'function' to the contents of the functor.
-
-        And returns a new functor value.
-        Is the opposite of :meth:`Fixable.fix`.
-        """
-
-
-@runtime
-class Fixable(Protocol[_ValueType, _ErrorType]):
-    """Represents containers that can be fixed and rescued."""
-
-    def fix(
-        self, function: Callable[[_ErrorType], _NewValueType],
-    ) -> 'Fixable[_NewValueType, _ErrorType]':
-        """
-        Applies 'function' to the error and transforms failure to success.
-
-        And returns a new functor value.
-        Works for containers that represent failure.
-        Is the opposite of :meth:`Mappable.map`.
-        """
-
-
-@runtime
-class Rescueable(Protocol[_NewValueType, _ErrorType]):
-    """
-    Represents a "context" in which calculations can be executed.
-
-    ``Rescueable`` allows you to bind together
-    a series of calculations while maintaining
-    the context of that specific container.
-    """
-
-    def rescue(
-        self,
-        function: Callable[
-            [_ErrorType], 'Rescueable[_NewValueType, _NewErrorType]',
-        ],
-    ) -> 'Rescueable[_NewValueType, _NewErrorType]':
-        """
-        Applies 'function' to the result of a previous calculation.
-
-        And returns a new container.
-        Works for containers that represent failure.
-        Is the opposite of :meth:`~bind`.
-        """
-
-
-@runtime
-class Unwrapable(Protocol[_ValueType, _ErrorType]):
-    """Represents containers that can unwrap and return its wrapped value."""
-
-    def value_or(
-        self, default_value: _NewValueType,
-    ) -> Union[_ValueType, _NewValueType]:
-        """Forces to unwrap value from container or return a default."""
-
-    def unwrap(self) -> _ValueType:
-        """
-        Custom magic method to unwrap inner value from container.
-
-        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`.
-        """
-
-    def failure(self) -> _ErrorType:
-        """
-        Custom magic method to unwrap inner value from the failed container.
-
-        This method is the opposite of :meth:`~unwrap`.
-        """
-
-
-@runtime
-class Altable(Protocol[_ValueType, _ErrorType]):
-    """Allows to unwrap failures."""
-
-    def alt(
-        self,
-        function: Callable[[_ErrorType], _NewErrorType],
-    ) -> 'Fixable[_ValueType, _NewErrorType]':
-        """
-        Uses 'function' to transform one error to another.
-
-        And returns a new functor value.
-        Works for containers that represent failure.
-        Is the opposite of :meth:`~map`.
-        """