Add @curry decorator

docs/pages/curry.rst

@@ -3,11 +3,16 @@
 Curry
 =====
 
-Python already has a great tool to use partial application:
+This module is dedicated to partial application.
+
+We support two types of partial application: ``@curry`` and ``partial``.
+
+``@curry`` is a new concept for most Python developers,
+but Python already has a great tool to use partial application:
 `functools.partial <https://docs.python.org/3/library/functools.html#functools.partial>`_
 
 The only problem with it is the lack of typing.
-Let's see what problems do we solve with our custom solution.
+Let's see what problems do we solve with this module.
 
 .. warning::
 
@@ -145,39 +150,133 @@ From this return type you can see that we work
 with all matching cases and discriminate unmatching ones.
 
 
-FAQ
----
+curry
+-----
 
-What is the difference between curring and partial?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``curry`` allows to provide only a subset of arguments to a function.
+And it won't be called untill all the required arguments are provided.
 
-This is a question a lot of Python developers ask.
+In contrast to ``partial`` which works on the calling stage,
+``@curry`` works best when defining a new function.
 
-`Here are some great answers <https://stackoverflow.com/questions/218025/what-is-the-difference-between-currying-and-partial-application>`_.
+.. code:: python
 
-.. warning::
+  >>> from returns.curry import curry
+
+  >>> @curry
+  ... def function(first: int, second: str) -> bool:
+  ...     return len(second) > first
+
+  >>> assert function(1)('a') is False
+  >>> assert function(1, 'a') is False
+  >>> assert function(2)('abc') is True
+  >>> assert function(2, 'abc') is True
+
+Take a note, that providing invalid arguments will raise ``TypeError``:
+
+.. code::
+
+  >>> function(1, 2, 3)
+  Traceback (most recent call last):
+    ...
+  TypeError: too many positional arguments
+
+  >>> function(a=1)
+  Traceback (most recent call last):
+    ...
+  TypeError: got an unexpected keyword argument 'a'
+
+This is really helpful when working with ``.apply()`` method of containers.
+
+Typing
+~~~~~~
+
+``@curry`` functions are also fully typed with our custom ``mypy`` plugin.
+
+Let's see how types do look like for a curried function:
+
+.. code:: python
 
-  Python has a very limited support for real curring in a way like
-  ``(x, y, z) -> t`` => ``x -> y -> z -> t``
-  works in languages like Haskell.
+  >>> from returns.curry import curry
 
-  This is actually a partial application, but that's the best we can do.
+  >>> @curry
+  ... def zero(a: int, b: float, *, kw: bool) -> str:
+  ...      return str(a - b) if kw else ''
+
+  >>> assert zero(1)(0.3)(kw=True) == '0.7'
+  >>> assert zero(1)(0.3, kw=False) == ''
+
+  # If we will reveal the type it would be quite big:
+
+  reveal_type(zero)
+
+  # Overload(
+  #   def (a: builtins.int) -> Overload(
+  #     def (b: builtins.float, *, kw: builtins.bool) -> builtins.str,
+  #     def (b: builtins.float) -> def (*, kw: builtins.bool) -> builtins.str
+  #   ),
+  #   def (a: builtins.int, b: builtins.float) -> def (*, kw: builtins.bool)
+  #     -> builtins.str,
+  #   def (a: builtins.int, b: builtins.float, *, kw: builtins.bool)
+  #     -> builtins.str
+  # )
+
+It reaveals to us that there are 4 possible way to call this function.
+And we type all of them with
+`overload <https://mypy.readthedocs.io/en/stable/more_types.html#function-overloading>`_
+type.
+
+When you provide any arguments,
+you discriminate some overloads and choose more specific path:
+
+.. code:: python
+
+  reveal_type(zero(1, 2.0))
+  # By providing this set of arguments we have choosen this path:
+  #
+  #   def (a: builtins.int, b: builtins.float) -> def (*, kw: builtins.bool)
+  #     -> builtins.str,
+  #
+  # And the revealed type would be:
+  #   def (*, kw: builtins.bool) -> builtins.str
+  #
+
+It works with functions, instance, class,
+and static methods, including generics.
+See ``Limitations`` in the API reference.
+
+
+FAQ
+---
 
 Why don't you support `*` and `**` arguments?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you use ``partial(some, *my_args)`` or ``partial(some, **my_args)``
 or both of them at the same time,
-we fallback to the default return type. Why?
+we fallback to the default return type. The same happens with ``curry``. Why?
+
+There are several problems:
+
+- Because ``mypy`` cannot not infer what arguments are there
+  inside this ``my_args`` variable
+- Because ``curry`` cannot know when
+  to stop accepting ``*args`` and ``**kwargs``
+- And there are possibly other problems!
+
+Our advice is not to use ``*args`` and ``*kwargs``
+with ``partial`` and ``curry``.
+
 
-Because ``mypy`` cannot not infer what arguments are there
-inside this ``my_args`` variable.
+Further reading
+---------------
 
-Our advice is not to use ``*args`` and ``*kwargs`` in ``partial`` call.
+- `functools.partial <https://docs.python.org/3/library/functools.html#functools.partial>`_
+- `Currying <https://en.wikipedia.org/wiki/Currying>`_
+- `@curry decorator <https://stackoverflow.com/questions/9458271/currying-decorator-in-python>`_
 
 
 API Reference
 -------------
 
 .. automodule:: returns.curry
-   :members:

returns/context/__init__.py

@@ -1,12 +1,13 @@
 """
-This module was quite big one, so we have split it.
+This module was quite a big one, so we have split it.
 
 isort:skip_file
 """
 
 from returns.context.requires_context import (  # noqa: F401
     Context as Context,
     RequiresContext as RequiresContext,
+    Reader as Reader,
     NoDeps as NoDeps,
 )
 from returns.context.requires_context_result import (  # noqa: F401

returns/context/requires_context.py

@@ -388,3 +388,9 @@ def ask(cls) -> RequiresContext[_EnvType, _EnvType]:
 
         """
         return RequiresContext(identity)
+
+
+# Aliases
+
+#: Sometimes `RequiresContext` is too long to type.
+Reader = RequiresContext

returns/context/requires_context_io_result.py

@@ -947,9 +947,6 @@ def from_failure(
         """
         return RequiresContextIOResult(lambda _: IOFailure(inner_value))
 
-    # TODO: support from_successful_result_context
-    # TODO: support from_failed_result_context
-
 
 @final
 class ContextIOResult(Immutable, Generic[_EnvType]):