Closes #124

Author: sobolevn

CHANGELOG.md

@@ -7,12 +7,21 @@ We follow Semantic Versions since the `0.1.0` release.
 
 ### Features
 
+- Now `bind` does not change the type of an error
+- Now `rescue` does not change the type of a value
+- Renames `map_failure` to `alt`
 - Adds `__hash__` magic methods to all containers
 
+### Bugfixes
+
+- Changes `Any` to `NoReturn` in `Success` and `Failure`
+- Now all type parameters in `Result`, `Maybe`, and `IO` are covariant
+
 ### Misc
 
 - Updates `mypy` version
 - Updates `wemake-python-styleguide` and introduces `nitpick`
+- Updates `pytest-plugin-mypy`
 
 
 ## 0.9.0

CONTRIBUTING.md

@@ -7,6 +7,7 @@ you will need to get familiar with these concepts:
 
 - http://learnyouahaskell.com/functors-applicative-functors-and-monoids
 - https://github.com/dbrattli/OSlash/wiki/Functors,-Applicatives,-And-Monads-In-Pictures
+- https://gcanti.github.io/fp-ts/
 
 Here are some practical examples of what we are doing here:
 

README.md

@@ -35,6 +35,8 @@ plugins =
   returns.contrib.mypy.decorator_plugin
 ```
 
+We also recommend to use the same `mypy` settings [we use](https://github.com/wemake-services/wemake-python-styleguide/blob/master/styles/mypy.toml).
+
 Make sure you know how to get started, [check out our docs](https://returns.readthedocs.io/en/latest/)!
 
 
@@ -155,12 +157,11 @@ and wrap it inside a new `Failure[Exception]`!
 And we can clearly see all result patterns
 that might happen in this particular case:
 - `Success[UserProfile]`
-- `Failure[HttpException]`
-- `Failure[JsonDecodeException]`
+- `Failure[Exception]`
 
 And we can work with each of them precisely.
-It is a good practice to create `Enum` classes or `Union` types
-with a list of all the possible errors.
+It is a good practice to create `Enum` classes or `Union` sum type
+with all the possible errors.
 
 
 ## IO marker

docs/pages/container.rst

@@ -57,11 +57,12 @@ is used to literally bind two different containers together.
 
   from returns.result import Result, Success
 
-  def may_fail(user_id: int) -> Result[int, str]:
+  def may_fail(user_id: int) -> Result[float, str]:
       ...
 
-  # Can be assumed as either Success[int] or Failure[str]:
-  result: Result[int, str] = Success(1).bind(may_fail)
+  value: Result[int, str] = Success(1)
+  # Can be assumed as either Success[float] or Failure[str]:
+  result: Result[float, str] = value.bind(may_fail)
 
 And we have :func:`~returns.primitives.container.Mappable.map`
 to use containers with regular functions.
@@ -105,7 +106,7 @@ It mean that our code can go on two tracks:
 2. Failed one: where something went wrong
 
 We can switch from track to track: we can fail something
-or we can rescue the situation.
+or we can fix the situation.
 
 .. mermaid::
   :caption: Railway oriented programming.
@@ -123,7 +124,7 @@ or we can rescue the situation.
        F2 -- Fix --> S3
        S3 -- Fail --> F4
        S5 -- Fail --> F6
-       F6 -- Rescue --> S7
+       F6 -- Fix --> S7
 
        style S1 fill:green
        style S3 fill:green
@@ -147,7 +148,7 @@ types like ``Failure``:
   transforms error to value (failure became success)
   that works only when container is in failed state,
   is the opposite of ``map`` method
-- :func:`~returns.primitives.container.UnwrapableFailure.map_failure`
+- :func:`~returns.primitives.container.UnwrapableFailure.alt`
   transforms error to another error
   that works only when container is in failed state,
   is the opposite of ``map`` method
@@ -162,7 +163,7 @@ during the pipeline execution:
   def double(state: int) -> float:
       return state * 2.0
 
-  result: Result[Any, float] = Failure(1).map_failure(double)
+  result: Result[Any, float] = Failure(1).alt(double)
   # => Failure(2.0)
 
   result: Result[float, int] = Failure(1).fix(double)
@@ -180,14 +181,12 @@ It can also rescue your flow and get on the successful track again:
           return Success(0)
       return Failure(state)
 
-  result: Result[int, Exception] = Failure(
-      ZeroDivisionError(),
-  ).rescue(tolerate_exception)
+  value: Result[int, Exception] = Failure(ZeroDivisionError())
+  result: Result[int, Exception] = value.rescue(tolerate_exception)
   # => Success(0)
 
-  result2: Result[int, Exception] = Failure(
-      ValueError(),
-  ).rescue(tolerate_exception)
+  value2: Result[int, Exception] = Failure(ValueError())
+  result2: Result[int, Exception] = value2.rescue(tolerate_exception)
   # => Failure(ValueError())
 
 

docs/pages/functions.rst

@@ -43,8 +43,7 @@ We allow you to do that with ease!
           """Imagine, that you need to reraise ValidationErrors due to API."""
           return self._validate_user(
               username,
-              # TODO: change in #84 to `.map_failure()`
-          ).fix(
+          ).alt(
               # What happens here is interesting, since you do not let your
               # unwrap to fail with UnwrapFailedError, but instead
               # allows you to reraise a wrapped exception.

docs/pages/result.rst

@@ -32,6 +32,37 @@ since it will raise ``TypeError`` somewhere
 and other ``None`` exception-friends.
 
 
+FAQ
+---
+
+How to create unit objects?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``Success`` or ``Failure`` together with the explicit annotation.
+Python's type system does not allow us to do much, so this is required:
+
+.. code:: python
+
+  def callback(arg: int) -> Result[float, int]:
+      return Success(float(arg))
+
+  first: Result[int, int] = Success(1)
+  first.bind(callback)
+
+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.
+
+
 is_successful
 -------------
 

returns/io.py

@@ -8,7 +8,7 @@
 
 from returns.primitives.container import BaseContainer
 
-_ValueType = TypeVar('_ValueType')
+_ValueType = TypeVar('_ValueType', covariant=True)
 _NewValueType = TypeVar('_NewValueType')
 
 # Helpers:

returns/maybe.py

@@ -8,6 +8,7 @@
     Callable,
     Coroutine,
     Generic,
+    NoReturn,
     Optional,
     TypeVar,
     Union,
@@ -19,10 +20,13 @@
 from returns.primitives.container import BaseContainer
 from returns.primitives.exceptions import UnwrapFailedError
 
-# Aliases:
-_ValueType = TypeVar('_ValueType')
+# Definitions:
+_ValueType = TypeVar('_ValueType', covariant=True)
 _NewValueType = TypeVar('_NewValueType')
-_ErrorType = TypeVar('_ErrorType')
+
+# Aliases:
+_FirstType = TypeVar('_FirstType')
+_SecondType = TypeVar('_SecondType')
 
 
 class Maybe(
@@ -113,7 +117,7 @@ def __init__(self, inner_value: None = None) -> None:
         """
         Wraps the given value in the Container.
 
-        'value' can only be ``None``.
+        ``inner_value`` can only be ``None``.
         """
         BaseContainer.__init__(self, inner_value)  # noqa: WPS609
 
@@ -221,26 +225,26 @@ def Some(inner_value: Optional[_ValueType]) -> Maybe[_ValueType]:  # noqa: N802
 
 
 #: Public unit value of protected `_Nothing` type.
-Nothing: Maybe[Any] = _Nothing()
+Nothing: Maybe[NoReturn] = _Nothing()
 
 
 @overload
 def maybe(  # type: ignore
     function: Callable[
         ...,
-        Coroutine[_ValueType, _ErrorType, Optional[_NewValueType]],
+        Coroutine[_FirstType, _SecondType, Optional[_ValueType]],
     ],
 ) -> Callable[
     ...,
-    Coroutine[_ValueType, _ErrorType, Maybe[_NewValueType]],
+    Coroutine[_FirstType, _SecondType, Maybe[_ValueType]],
 ]:
     """Case for async functions."""
 
 
 @overload
 def maybe(
-    function: Callable[..., Optional[_NewValueType]],
-) -> Callable[..., Maybe[_NewValueType]]:
+    function: Callable[..., Optional[_ValueType]],
+) -> Callable[..., Maybe[_ValueType]]:
     """Case for regular functions."""
 
 

returns/primitives/container.py

@@ -111,7 +111,7 @@ def fix(
 
 
 @runtime
-class Rescueable(Protocol[_ValueType, _ErrorType]):
+class Rescueable(Protocol[_NewValueType, _ErrorType]):
     """
     Represents a "context" in which calculations can be executed.
 
@@ -159,7 +159,7 @@ def unwrap(self) -> _ValueType:
 class UnwrapableFailure(Protocol[_ValueType, _ErrorType]):
     """Allows to unwrap failures."""
 
-    def map_failure(
+    def alt(
         self,
         function: Callable[[_ErrorType], _NewErrorType],
     ) -> 'Fixable[_ValueType, _NewErrorType]':