Adds converters, closes #92

Author: sobolevn

CHANGELOG.md

@@ -8,6 +8,7 @@ We follow Semantic Versions since the `0.1.0` release.
 ### Features
 
 - Reintroduces the `Maybe` monad, typed!
+- Introduces converters from one type to another
 - Adds `mypy` plugin to type decorators
 - Complete rewrite of `Result` types
 - Partial API change, now `Success` and `Failure` are not types, but functions

docs/pages/container.rst

@@ -293,10 +293,46 @@ Here's the full table of compositions that make sense:
 
 - ``IO[Result[A, B]]`` ✅
 - ``Result[IO[A], B]`` ✅
+- ``IO[Maybe[A]]`` ✅
+- ``Maybe[IO[A]]`` ✅
 - ``IO[IO[A]]`` 🚫
 - ``Result[A, IO[A]]`` 🚫
+- ``Result[Maybe[A], B]`` 🚫
+- ``Result[A, Maybe[B]]`` 🚫
 - ``Result[Result[A, B], C]`` 🚫
 - ``Result[A, Result[B, C]]`` 🚫
+- ``Maybe[Result[A, B]]`` 🚫
+
+You can use :ref:`converters` to convert ``Maybe`` and ``Result`` containers.
+So, you don't have to compose them.
+
+
+.. converters_:
+
+Converters
+----------
+
+We have several helper functions
+to convert containers from ``Maybe`` to ``Result`` and back again:
+
+- ``maybe_to_result`` that converts ``Maybe`` to ``Result``
+- ``result_to_maybe`` that converts ``Result`` to ``Maybe``
+
+That's how they work:
+
+.. code:: python
+
+  from returns.converters import maybe_to_result, result_to_maybe
+  from returns.maybe import Maybe
+  from returns.result import Result
+
+  result: Result[int, Exception]
+  maybe: Maybe[int] = result_to_maybe(result)
+  new_result: Result[int, None] = maybe_to_result(maybe)
+
+Take a note, that type changes.
+Also, take a note that ``Success(None)`` will be converted to ``Nothing``.
+
 
 API Reference
 -------------

docs/pages/io.rst

@@ -220,7 +220,6 @@ since ``IO`` operation is safe and cannot throw.
 .. code:: python
 
   import requests
-
   from returns.io import IO, impure
   from returns.result import Result, safe
 
@@ -233,6 +232,39 @@ since ``IO`` operation is safe and cannot throw.
 In this case the whole result is marked as impure.
 Since its failures are impure as well.
 
+What is the difference between IO[Maybe[A]] and Maybe[IO[A]]?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The similar question is about ``IO`` and ``Maybe`` composition.
+Let's illustrate it with the code example:
+
+.. code:: python
+
+  from returns.maybe import Maybe, Nothing
+  from returns.io import IO
+
+  def maybe_ask_user(should_ask: bool) -> Maybe[IO[str]]:
+      if should_ask:
+          return Maybe.new(IO(input('Asking!')))
+      return Nothing
+
+In this example ``IO`` might not happen at all.
+
+.. code:: python
+
+  from returns.maybe import Maybe, Nothing
+  from returns.io import IO
+
+  def ask_user() -> IO[Maybe[str]]:
+      prompt = input('Asking!')
+      if prompt:
+          return Maybe.new(IO(prompt))
+      return IO(Nothing)
+
+In this second case, we always do ``IO``, but we return ``Nothing``
+if user inputs an empty string
+(because we need this business logic for some reason).
+
 Why can't we unwrap values or use @pipeline with IO?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

returns/converters.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+from returns.maybe import Maybe
+from returns.result import Failure, Success
+
+
+def result_to_maybe(result_container):
+    """Converts ``Result`` container to ``Maybe`` container."""
+    return Maybe.new(result_container.value_or(None))
+
+
+def maybe_to_result(maybe_container):
+    """Converts ``Maybe`` container to ``Result`` container."""
+    inner_value = maybe_container.value_or(None)
+    if inner_value is not None:
+        return Success(inner_value)
+    return Failure(inner_value)

returns/converters.pyi

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+from typing import TypeVar
+
+from returns.maybe import Maybe
+from returns.result import Result
+
+_ValueType = TypeVar('_ValueType')
+_ErrorType = TypeVar('_ErrorType')
+
+
+def result_to_maybe(
+    result_container: Result[_ValueType, _ErrorType],
+) -> Maybe[_ValueType]:
+    ...
+
+
+def maybe_to_result(
+    maybe_container: Maybe[_ValueType],
+) -> Result[_ValueType, None]:
+    ...

returns/maybe.py

@@ -143,7 +143,7 @@ def failure(self):
 
 def Some(inner_value):  # noqa: N802
     """Public unit function of protected `_Some` type."""
-    return _Some(inner_value)
+    return Maybe.new(inner_value)
 
 
 #: Public unit value of protected `_Nothing` type.

tests/test_converters/test_maybe_to_result.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from returns.converters import maybe_to_result
+from returns.maybe import Nothing, Some
+from returns.result import Failure, Success
+
+
+@pytest.mark.parametrize('inner_value', [
+    1,
+    [],
+    '',
+])
+def test_some_to_success(inner_value):
+    """Ensures that `Some` is always converted to `Success`."""
+    assert maybe_to_result(Some(inner_value)) == Success(inner_value)
+
+
+def test_nothing_to_failure():
+    """Ensure that `Nothing` is always converted to `Failure`."""
+    assert maybe_to_result(Nothing) == Failure(None)
+    assert maybe_to_result(Some(None)) == Failure(None)

tests/test_converters/test_result_to_maybe.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+import pytest
+
+from returns.converters import result_to_maybe
+from returns.maybe import Nothing, Some
+from returns.result import Failure, Success
+
+
+@pytest.mark.parametrize('inner_value', [
+    1,
+    [],
+    '',
+])
+def test_success_to_some(inner_value):
+    """Ensures that `Success` is always converted to `Some`."""
+    assert result_to_maybe(Success(inner_value)) == Some(inner_value)
+
+
+def test_success_to_nothing():
+    """Ensures that `Success(None_` is always converted to `Nothing`."""
+    assert result_to_maybe(Success(None)) == Nothing
+
+
+@pytest.mark.parametrize('inner_value', [
+    Exception,
+    0,
+    None,
+])
+def test_failure_to_nothing(inner_value):
+    """Ensures that `Failure` is always converted to `Nothing`."""
+    assert result_to_maybe(Failure(inner_value)) == Nothing

tests/test_maybe/test_maybe_equality.py

@@ -11,7 +11,7 @@ def test_equality():
     assert Nothing is Nothing  # noqa: Z312
     assert Nothing == _Nothing() == _Nothing(None)
     assert Some(5) == Some(5)
-    assert Some(None) == Some(None)
+    assert Some(None) == Nothing
 
 
 def test_nonequality():
@@ -22,7 +22,6 @@ def test_nonequality():
     assert _Nothing(None) != None  # noqa: E711
     assert Some(5) != 5
     assert Some(3) is not Some(3)
-    assert Some(None) != Nothing
 
 
 def test_is_compare():

tests/test_maybe/test_maybe_new.py

@@ -11,3 +11,8 @@ def test_maybe_new_some():
 def test_maybe_new_nothing():
     """Ensures that `new` works for Nothing container."""
     assert Maybe.new(None) == Nothing
+
+
+def test_some_from_none():
+    """Ensure that `Some(None) == Nothing`."""
+    assert Some(None) == Nothing