Adds flatten support for RequiresContextResult

Author: sobolevn

CHANGELOG.md

@@ -26,6 +26,7 @@ See [0Ver](https://0ver.org/).
 - Adds `RequiresContextResultE` alias
   for `RequiresContextResult[..., ..., Exception]`
 - Adds `RequiresContextResult` support for `bind` and `rescue`
+- Adds `RequiresContextResult` support for `flatten`
 
 - Adds `IOResult` helper to work better with `IO[Result[a, b]]`
 - Adds `IOResultE` alias for `IOResult[a, Exception]`
@@ -37,7 +38,7 @@ See [0Ver](https://0ver.org/).
 
 - Adds `Result.lift`, `Maybe.lift`, `RequiresContext.lift`,
   and `RequiresContextResult.lift` functions in addition to `IO.lift`
-- Adds
+- Adds `Immutable` primitive type
 
 
 ### Bugfixes

docs/index.rst

@@ -36,6 +36,7 @@ Contents
   pages/converters.rst
   pages/pointfree.rst
   pages/functions.rst
+  pages/types.rst
 
 .. toctree::
   :maxdepth: 1

docs/pages/container.rst

@@ -100,10 +100,13 @@ Note::
   All containers support these methods.
 
 
+.. _immutability:
+
 Immutability
 ------------
 
-We like to think of ``returns`` as immutable structures.
+We like to think of ``returns``
+as :ref:`immutable <primitive-types>` structures.
 You cannot mutate the inner state of the created container,
 because we redefine ``__setattr__`` and ``__delattr__`` magic methods.
 
@@ -174,6 +177,13 @@ Needs transformation
 - ``Maybe[Result[A, B]]`` 🤔,
   use :func:`result_to_maybe <returns.converters.result_to_maybe>`
   and then :func:`flatten <returns.converters.flatten>`
+- ``RequiresContext[env, Result[A, B]]`` 🤔,
+  use :meth:`returns.context.requires_context_result.from_typecast`
+  and ``RequiresResultContext``
+- ``RequiresContext[env, RequiresContext[env, A]]`` 🤔,
+  use :func:`flatten <returns.converters.flatten>`
+- ``RequiresContextResult[env, RequiresContextResult[env, A, B], B]`` 🤔,
+  use :func:`flatten <returns.converters.flatten>`
 
 Nope
 ~~~~

docs/pages/context.rst

@@ -136,6 +136,8 @@ Let's see how our code changes:
 
 And now you can pass your dependencies in a really direct and explicit way.
 
+.. _ask:
+
 ask
 ~~~
 
@@ -277,15 +279,71 @@ Use it when you work with pure context-related functions that might fail.
 FAQ
 ---
 
-Why do I have to use explicit type annotation for ask method?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Why can’t we use RequiresContext[e, Result] instead of RequiresContextResult?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We actually can! But, it is harder to write.
+And ``RequiresContextResult`` is actually
+the very same thing as ``RequiresContext[e, Result]``, but has nicer API:
+
+.. code:: python
+
+  x: RequiresContext[int, Result[int, str]]
+  x.map(lambda result: result.map(lambda number: number + 1))
+
+  # Is the same as:
+
+  y: RequiresContextResult[int, int, str]
+  y.map(lambda number: number + 1)
+
+The second one looks better, doesn't it?
 
 How to create unit objects?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+``RequiresContext`` allows you to create
+unit values with the help of ``.from_value`` method:
+
+.. code:: python
+
+  >>> from returns.context import RequiresContext
+  >>> assert RequiresContext.from_value(1)(...) == 1
+
+``RequiresContextResult`` requires you to use one of the following methods:
+
+- ``from_success`` when you want to mark some raw value as a ``Success``
+- ``from_failure`` when you want to mark some raw value as a ``Failure``
+- ``from_result`` when you already have one
+- ``from_successful_context`` when you have successful ``RequiresContext``
+- ``from_failed_context`` when you have failed ``RequiresContext``
+
+But, think twice: why would you need to do it?
+These classes represent computations that rely on context.
+Maybe, you should not do creat their units?
+
 How can I access dependencies inside the context?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Use ``.ask()`` method!
+
+See :ref:`this guide <ask>`.
+
+Why do I have to use explicit type annotation for ask method?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because ``mypy`` cannot possibly know the type of current context.
+This is hard even for a plugin.
+
+So, using this technique is better:
+
+.. code:: python
+
+  from returns.context import Context, RequiresContext
+
+  def some_context(*args, **kwargs) -> RequiresContext[int, str]:
+      def factory(deps: int) -> RequiresContext[int, str]:
+          ...
+      return Context[int].ask().bind(factory)
 
 
 Further reading

docs/pages/io.rst

@@ -454,19 +454,20 @@ but has nicer API:
 
 The second one looks better, doesn't it?
 
-How to create unit object for IOResult?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How to create unit objects for IOResult?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*TLDR*: you need to explicitly annotate values like so:
+*TLDR*: you need to use ``IOSuccess`` and ``IOFailure``:
 
 .. code:: python
 
   >>> from returns.io import IOResult, IOSuccess, IOFailure
   >>> first: IOResult[int, str] = IOSuccess(1)
   >>> second: IOResult[float, int] = IOFailure(1)
 
+You can also annotate your variables properly.
 Otherwise, ``mypy`` will treat ``IOSuccess(1)`` as ``IOSuccess[int, Any]``.
-You need to narrow the type.
+You can narrow the type in advance.
 
 See :ref:`result-units` for more details.
 
@@ -491,7 +492,8 @@ Warning::
   the internal state of the IO with ``._internal_state``,
   but your are considered to be a grown-up!
 
-  Use wemake-python-styleguide to restrict `._` access in your code.
+Use `wemake-python-styleguide <https://github.com/wemake-services/wemake-python-styleguide>`_
+to restrict ``._`` access in your code.
 
 
 Further reading

docs/pages/types.rst

@@ -0,0 +1,24 @@
+.. _primitive-types:
+
+Primitive types
+===============
+
+We have several utility types that we use for our containers,
+that can also help end users as well.
+
+
+Immutable
+---------
+
+This class is useful when you need
+to make some instances immutable
+(like :ref:`our containers are <immutability>`).
+
+
+API Reference
+-------------
+
+.. autoclasstree:: returns.primitives.types
+
+.. automodule:: returns.primitives.types
+   :members:

returns/_generated/flatten.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+from returns.functions import identity
+
 
 def _flatten(container):
     """
@@ -15,7 +17,7 @@ def _flatten(container):
       >>> from returns.maybe import Some
       >>> from returns.result import Failure, Success
       >>> from returns.io import IO, IOSuccess, IOFailure
-      >>> from returns.context import RequiresContext
+      >>> from returns.context import RequiresContext, RequiresContextResult
 
       >>> assert flatten(IO(IO(1))) == IO(1)
 
@@ -31,8 +33,14 @@ def _flatten(container):
       ...     RequiresContext.from_value(RequiresContext.from_value(1)),
       ... )(RequiresContext.empty) == 1
 
+      >>> assert flatten(
+      ...     RequiresContextResult.from_success(
+      ...         RequiresContextResult.from_success(1),
+      ...     ),
+      ... )(RequiresContext.empty) == Success(1)
+
     See also:
         https://bit.ly/2sIviUr
 
     """
-    return container.bind(lambda identity: identity)  # we cannot import it :(
+    return container.bind(identity)

returns/_generated/flatten.pyi

@@ -2,7 +2,7 @@
 
 from typing import TypeVar, overload
 
-from returns.context import RequiresContext
+from returns.context import RequiresContext, RequiresContextResult
 from returns.io import IO, IOResult
 from returns.maybe import Maybe
 from returns.result import Result
@@ -43,3 +43,15 @@ def _flatten(
     ],
 ) -> RequiresContext[_EnvType, _ValueType]:
     ...
+
+
+
+@overload
+def _flatten(
+    container: RequiresContextResult[
+        _EnvType,
+        RequiresContextResult[_EnvType, _ValueType, _ErrorType],
+        _ErrorType,
+    ],
+) -> RequiresContextResult[_EnvType, _ValueType, _ErrorType]:
+    ...

returns/context/requires_context.py

@@ -6,7 +6,7 @@
 
 from returns.functions import identity
 from returns.primitives.container import BaseContainer
-from returns.primitives.types import Immutable, Stateless
+from returns.primitives.types import Immutable
 
 # Context:
 _EnvType = TypeVar('_EnvType', contravariant=True)
@@ -226,11 +226,7 @@ def from_value(
 
 
 @final
-class Context(
-    Immutable,
-    Stateless,
-    Generic[_EnvType],
-):
+class Context(Immutable, Generic[_EnvType]):
     """
     Helpers that can be used to work with ``RequiresContext`` container.
 

returns/context/requires_context_result.py

@@ -6,7 +6,7 @@
 
 from returns.context.requires_context import RequiresContext
 from returns.primitives.container import BaseContainer
-from returns.primitives.types import Immutable, Stateless
+from returns.primitives.types import Immutable
 from returns.result import Failure, Result, Success
 
 # Context:
@@ -649,11 +649,7 @@ def from_failure(
 
 
 @final
-class ContextResult(
-    Immutable,
-    Stateless,
-    Generic[_EnvType],
-):
+class ContextResult(Immutable, Generic[_EnvType]):
     """
     Helpers that can be used to work with ``RequiresContextResult`` container.