WIP: rewrites types for Result monad (#86)

* WIP: rewrites types for Result monad

* WIP: rewrites types for Result monad

* Adds docs

* Adds docs

Author: sobolevn

CHANGELOG.md

@@ -7,11 +7,19 @@ We follow Semantic Versions since the `0.1.0` release.
 
 ### Features
 
-- New types introduced: `FixableContainer` and `ValueUnwrapContainer`
+- Complete rewrite of `Result` types
+- Partial API change, now `Success` and `Failure` are not types, but functions
+- New internal types introduced: `FixableContainer` and `ValueUnwrapContainer`
+
+### Bugfixes
+
+- Fixes issue when you could return `IO` container from `Result.bind`
+- Fixes `@pipeline` return type
 
 ### Misc
 
 - Improved docs about `IO` and `Container` concept
+- Adds docs about container composition
 
 
 ## 0.7.0

docs/pages/container.rst

@@ -53,22 +53,23 @@ is used to literally bind two different containers together.
   def may_fail(user_id: int) -> Result[int, str]:
       ...
 
-  result = Success(1).bind(may_fail)
-  # => Either Success[int] or Failure[str]
+  # Can be assumed as either Success[int] or Failure[str]:
+  result: Result[int, str] = Success(1).bind(may_fail)
 
 And we have :func:`.map <returns.primitives.container.Container.map>`
 to use containers with regular functions.
 
 .. code:: python
 
-  from returns.result import Success
+  from typing import Any
+  from returns.result import Success, Result
 
   def double(state: int) -> int:
       return state * 2
 
-  result = Success(1).map(double)
+  result: Result[int, Any] = Success(1).map(double)
   # => Success(2)
-  result.map(lambda state: state + 1)
+  result: Result[int, Any] = result.map(lambda state: state + 1)
   # => Success(3)
 
 The same work with built-in functions as well:
@@ -144,12 +145,12 @@ during the pipeline execution:
 
 .. code:: python
 
-  from returns.result import Failure
+  from returns.result import Failure, Result
 
   def double(state: int) -> float:
       return state * 2.0
 
-  Failure(1).fix(double)
+  result: Result[float, int] = Failure(1).fix(double)
   # => Success(2.0)
 
 ``rescue`` should return one of ``Success`` or ``Failure`` types.
@@ -164,12 +165,17 @@ It can also rescue your flow and get on the successful track again:
           return Success(0)
       return Failure(state)
 
-  Failure(ZeroDivisionError()).rescue(tolerate_exception)
+  result: Result[int, Exception] = Failure(
+      ZeroDivisionError(),
+  ).rescue(tolerate_exception)
   # => Success(0)
 
-  Failure(ValueError()).rescue(tolerate_exception)
+  result2: Result[int, Exception] = Failure(
+      ValueError(),
+  ).rescue(tolerate_exception)
   # => Failure(ValueError())
 
+
 Note::
 
   Not all containers support these methods.
@@ -257,6 +263,10 @@ when they install our application.
 However, this is still good old ``python`` type system,
 and it has its drawbacks.
 
+You can have a look at the suggested ``mypy``
+`configuration <https://github.com/dry-python/returns/blob/master/setup.cfg>`_
+in our own repository.
+
 
 API Reference
 -------------

docs/pages/functions.rst

@@ -41,21 +41,22 @@ We allow you to do that with ease!
       @pipeline
       def __call__(self, username: str) -> ...:
           """Imagine, that you need to reraise ValidationErrors due to API."""
-          user_schema = self._validate_user(
-            username,
+          return self._validate_user(
+              username,
+              # TODO: change in #84 to `.map_failure()`
           ).fix(
-            # 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.
-            # In this case `ValidationError()` will be thrown
-            # before `UnwrapFailedError`
-            raise_exception,
-          ).unwrap()
+              # 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.
+              # In this case `ValidationError()` will be thrown
+              # before `UnwrapFailedError`
+              raise_exception,
+          )
 
       def _validate_user(
-        self, username: str,
+          self, username: str,
       ) -> Result['User', ValidationError]:
-        ...
+          ...
 
 Use this with caution. We try to remove exceptions from our code base.
 Original proposal is `here <https://github.com/dry-python/returns/issues/56>`_.

docs/pages/result.rst

@@ -196,7 +196,7 @@ Supports both async and regular functions.
 
   from returns.result import safe
 
-  @safe
+  @safe  # Will convert type to: Callable[[int], Result[float, Exception]]
   def divide(number: int) -> float:
       return number / number