WIP: adds hkt support

CHANGELOG.md

@@ -6,6 +6,46 @@ incremental in minor, bugfixes only are patches.
 See [0Ver](https://0ver.org/).
 
 
+## 0.15.0 WIP
+
+### Features
+
+- Adds Higher Kinded Types partial support
+- **Breaking**: makes our `mypy` plugin not optional, but required!
+- **Breaking**: changes all `RequiresContext`-based type arguments order,
+  previously we used to specify `_EnvType` as the first type argument,
+  now it is the last one. This is done to respect new HKT rules
+- **Breaking**: removes all old interfaces from `primitives/interfaces.py`,
+  use new typeclasses instead
+- **Breaking**: removes `value_or` pointfree method,
+  because it is impossible to express with HKT
+- **Breaking**: removes `.value_or`, `.unwrap`, and `.failure` methods
+  from `FutureResult` and `RequiresContext` based types,
+  because we do require these methods to raise an exception on failure,
+  but these methods were lazy and did not raise the required exception
+- **Breaking**: changes how `is_successful` is typed:
+  now we allow any `Unwrappable` interface instances there,
+  including custom ones
+- **Breaking**: changes `UnwrapFailedError` constructor,
+  now it does accept an `Unwrappable` instance instead of a `BaseContainer`
+- Adds new public interfaces: see `returns.interfaces`
+- Adds `methods` package with all the composition methods we support
+- Adds `collect_trace` helper function for better development experience
+- Adds missing `from_requires_context_future_result` to `RequiresContext`
+- Adds `@abstractmethod` to abstract methods in abstract containers
+  like `Result`, `Maybe`, and `IOResult`
+- Adds `__slots__` to `UnwrapFailedError` with `halted_container`
+
+### Bugfixes
+
+- **Breaking**: fixes serious typing issue and changes how `flow` works,
+  now it has a hard limit of 21 parameters: 1 instance + 20 functions
+
+### Misc
+
+- Adds a lot of new typetests
+
+
 ## 0.14.0
 
 ### Features

README.md

@@ -32,7 +32,7 @@ Make your functions return something meaningful, typed, and safe!
 pip install returns
 ```
 
-You might also want to [configure](https://returns.readthedocs.io/en/latest/pages/container.html#type-safety)
+You are also required to [configure](https://returns.readthedocs.io/en/latest/pages/container.html#type-safety)
 `mypy` correctly and install our plugin
 to fix [this existing issue](https://github.com/python/mypy/issues/3157):
 
@@ -123,7 +123,7 @@ Much better, isn't it?
 
 ## RequiresContext container
 
-Many developers do use some kind of [dependency injection](https://github.com/dry-python/dependencies) in Python.
+Many developers do use some kind of dependency injection in Python.
 And usually it is based on the idea
 that there's some kind of a container and assembly process.
 
@@ -193,11 +193,11 @@ from returns.context import RequiresContext
 class _Deps(Protocol):  # we rely on abstractions, not direct values or types
     WORD_THRESHOLD: int
 
-def calculate_points(word: str) -> RequiresContext[_Deps, int]:
+def calculate_points(word: str) -> RequiresContext[int, _Deps]:
     guessed_letters_count = len([letter for letter in word if letter != '.'])
     return _award_points_for_letters(guessed_letters_count)
 
-def _award_points_for_letters(guessed: int) -> RequiresContext[_Deps, int]:
+def _award_points_for_letters(guessed: int) -> RequiresContext[int, _Deps]:
     return RequiresContext(
         lambda deps: 0 if guessed < deps.WORD_THRESHOLD else guessed,
     )
@@ -208,7 +208,7 @@ And have the type-safety to check what you pass to cover your back.
 Check out [RequiresContext](https://returns.readthedocs.io/en/latest/pages/context.html) docs for more. There you will learn how to make `'.'` also configurable.
 
 We also have [RequiresContextResult](https://returns.readthedocs.io/en/latest/pages/context.html#requirescontextresult-container)
-for context-related operations that might fail.
+for context-related operations that might fail. And also [RequiresContextIOResult](https://returns.readthedocs.io/en/latest/pages/context.html#requirescontextioresult-container) and [RequiresContextFutureResult](https://returns.readthedocs.io/en/latest/pages/context.html#requirescontextfutureresult-container).
 
 
 ## Result container

docs/index.rst

@@ -18,6 +18,8 @@ Contents
 
   pages/container.rst
   pages/railway.rst
+  pages/hkt.rst
+  pages/interfaces.rst
 
 .. toctree::
   :maxdepth: 2
@@ -35,6 +37,7 @@ Contents
 
   pages/pipeline.rst
   pages/converters.rst
+  pages/methods.rst
   pages/pointfree.rst
   pages/functions.rst
   pages/curry.rst

docs/pages/container.rst

@@ -69,7 +69,7 @@ The difference is simple:
 - ``map`` works with functions that return regular value
 - ``bind`` works with functions that return new container of the same type
 
-:func:`~returns.primitives.container.Bindable.bind`
+:func:`returns.primitives.container.Bindable.bind`
 is used to literally bind two different containers together.
 
 .. code:: python
@@ -83,7 +83,7 @@ is used to literally bind two different containers together.
   # 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`
+And we have :func:`returns.interfaces.mappable.Mappable.map`
 to use containers with regular functions.
 
 .. code:: python
@@ -335,11 +335,3 @@ It defines some basic things like representation, hashing, pickling, etc.
 .. automodule:: returns.primitives.container
    :members:
    :special-members:
-
-Here are our interfaces (or protocols to be more specific)
-that we use inside our app:
-
-.. autoclasstree:: returns.primitives.interfaces
-
-.. automodule:: returns.primitives.interfaces
-   :members:

docs/pages/context.rst

@@ -1,7 +1,7 @@
 Context
 =======
 
-`Dependency injection <https://github.com/dry-python/dependencies>`_ is a popular software architechture pattern.
+Dependency injection is a popular software architechture pattern.
 
 It's main idea is that you provide `Inversion of Control <https://en.wikipedia.org/wiki/Inversion_of_control>`_
 and can pass different things into your logic instead of hardcoding you stuff.
@@ -125,11 +125,11 @@ Let's see how our code changes:
   class _Deps(Protocol):  # we rely on abstractions, not direct values or types
       WORD_THRESHOLD: int
 
-  def calculate_points(word: str) -> RequiresContext[_Deps, int]:
+  def calculate_points(word: str) -> RequiresContext[int, _Deps]:
       guessed_letters_count = len([letter for letter in word if letter != '.'])
       return _award_points_for_letters(guessed_letters_count)
 
-  def _award_points_for_letters(guessed: int) -> RequiresContext[_Deps, int]:
+  def _award_points_for_letters(guessed: int) -> RequiresContext[int, _Deps]:
       return RequiresContext(
           lambda deps: 0 if guessed < deps.WORD_THRESHOLD else guessed,
       )
@@ -149,7 +149,7 @@ How can we do that with our existing function?
 
 .. code:: python
 
-  def calculate_points(word: str) -> RequiresContext[_Deps, int]:
+  def calculate_points(word: str) -> RequiresContext[int, _Deps]:
       guessed_letters_count = len([letter for letter in word if letter != '.'])
       return _award_points_for_letters(guessed_letters_count)
 
@@ -173,8 +173,8 @@ Let's see the final result:
       WORD_THRESHOLD: int
       UNGUESSED_CHAR: str
 
-  def calculate_points(word: str) -> RequiresContext[_Deps, int]:
-      def factory(deps: _Deps) -> RequiresContext[_Deps, int]:
+  def calculate_points(word: str) -> RequiresContext[int, _Deps]:
+      def factory(deps: _Deps) -> RequiresContext[int, _Deps]:
           guessed_letters_count = len([
               letter for letter in word if letter != deps.UNGUESSED_CHAR
           ])
@@ -203,7 +203,7 @@ It can be illustrated as a simple nested function:
   ...     def inner(deps: str) -> bool:
   ...         return len(deps) > limit
   ...     return inner
-  ...
+
   >>> assert first(2)('abc')  # first(limit)(deps)
   >>> assert not first(5)('abc')  # first(limit)(deps)
 
@@ -225,7 +225,7 @@ We can wrap it in ``RequiresContext`` container to allow better composition!
 
   >>> from returns.context import RequiresContext
 
-  >>> def first(limit: int) -> RequiresContext[str, bool]:
+  >>> def first(limit: int) -> RequiresContext[bool, str]:
   ...     def inner(deps: str) -> bool:
   ...         return len(deps) > limit
   ...     return RequiresContext(inner)  # wrapping function here!
@@ -252,7 +252,7 @@ And then normal logical execution happens.
 RequiresContextResult container
 -------------------------------
 
-This container is a combintaion of ``RequiresContext[env, Result[a, b]]``.
+This container is a combintaion of ``RequiresContext[Result[a, b], env]``.
 Which means that it is a wrapper around pure function that might fail.
 
 We also added a lot of useful methods for this container,
@@ -272,7 +272,7 @@ Use it when you work with pure context-related functions that might fail.
 RequiresContextIOResult container
 ---------------------------------
 
-This container is a combintaion of ``RequiresContext[env, IOResult[a, b]]``.
+This container is a combintaion of ``RequiresContext[IOResult[a, b], env]``.
 Which means that it is a wrapper around impure function that might fail.
 
 We also added a lot of useful methods for this container,
@@ -301,7 +301,7 @@ This is basically **the main type** that is going to be used in most apps.
 RequiresContextFutureResult container
 -------------------------------------
 
-This container is a combintaion of ``RequiresContext[env, FutureResult[a, b]]``.
+This container is a combintaion of ``RequiresContext[FutureResult[a, b], env]``.
 Which means that it is a wrapper around impure async function that might fail.
 
 Here's how it should be used:
@@ -334,7 +334,7 @@ Here's how it should be used:
 
   def _fetch_post(
       post_id: int,
-  ) -> RequiresContextFutureResultE[httpx.AsyncClient, _Post]:
+  ) -> RequiresContextFutureResultE[_Post, httpx.AsyncClient]:
       return ContextFutureResult[httpx.AsyncClient].ask().bind_future_result(
           lambda client: future_safe(client.get)(_URL.format(post_id)),
       ).bind_result(
@@ -345,7 +345,7 @@ Here's how it should be used:
 
   def show_titles(
       number_of_posts: int,
-  ) -> RequiresContextFutureResultE[httpx.AsyncClient, Sequence[_TitleOnly]]:
+  ) -> RequiresContextFutureResultE[Sequence[_TitleOnly], httpx.AsyncClient]:
       return RequiresContextFutureResultE.from_iterable([
           # Notice how easily we compose async and sync functions:
           _fetch_post(post_id).map(lambda post: post['title'])
@@ -549,7 +549,7 @@ We can model the similar idea with ``RequiresContext``:
 
   >>> from returns.context import RequiresContext
 
-  >>> def my_function(first: int, second: int) -> RequiresContext[bool, int]:
+  >>> def my_function(first: int, second: int) -> RequiresContext[int, bool]:
   ...     def factory(print_result: bool) -> int:
   ...         original = first + second
   ...         if print_result:
@@ -566,21 +566,21 @@ it is easier to change the behaviour of a function with ``RequiresContext``.
 While decorator with arguments glues values to a function forever.
 Decide when you need which behaviour carefully.
 
-Why can’t we use RequiresContext[e, Result] instead of RequiresContextResult?
+Why can’t we use RequiresContext[Result, e] 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:
+the very same thing as ``RequiresContext[Result, e]``, but has nicer API:
 
 .. code:: python
 
-  x: RequiresContext[int, Result[int, str]]
+  x: RequiresContext[Result[int, str], int]
   x.map(lambda result: result.map(lambda number: number + 1))
 
   # Is the same as:
 
-  y: RequiresContextResult[int, int, str]
+  y: RequiresContextResult[int, str, int]
   y.map(lambda number: number + 1)
 
 The second one looks better, doesn't it?
@@ -599,8 +599,8 @@ So, using this technique is better:
 
   from returns.context import Context, RequiresContext
 
-  def some_context(*args, **kwargs) -> RequiresContext[int, str]:
-      def factory(deps: int) -> RequiresContext[int, str]:
+  def some_context(*args, **kwargs) -> RequiresContext[str, int]:
+      def factory(deps: int) -> RequiresContext[str, int]:
           ...
       return Context[int].ask().bind(factory)
 
@@ -615,7 +615,7 @@ that do pretty much the same as ``RequiresContext`` container.
 What is the difference? Why do we need each of them?
 
 Let's find out!
-Tools like `dependencies <https://github.com/dry-python/dependencies>`_
+Tools like `dependencies <https://github.com/proofit404/dependencies>`_
 or `punq <https://github.com/bobthemighty/punq>`_
 tries to:
 
@@ -635,7 +635,7 @@ All it does is: provides simple API to compose functions
 that need additional context (or dependencies) to run.
 
 You can even use them together: ``RequiresContext`` will pass depedencies
-built by ``dry-python/dependencies`` (or any other tool of your choice)
+built by ``punq`` (or any other tool of your choice)
 as a ``deps`` parameter to ``RequiresContext`` instance.
 
 When to use which? Let's dig into it!

docs/pages/contrib/mypy_plugins.rst

@@ -49,13 +49,15 @@ This will allow to keep them in sync with the upstream.
 Supported features
 ------------------
 
+- ``kind`` feature adds Higher Kinded Types (HKT) support
 - ``curry`` feature allows to write typed curried functions
 - ``partial`` feature allows to write typed partial application
 - ``flow`` feature allows to write better typed functional pipelines
+  with ``flow`` function
+- ``pipe`` feature allows to write better typed functional pipelines
+  with ``pipe`` function
 - ``decorators`` allows to infer types of functions that are decorated
   with ``@safe``, ``@maybe``, ``@impure``, etc
-- ``pointfree`` provides better typing inference
-  for some problematic :ref:`pointfree` helpers
 
 
 Further reading
@@ -71,11 +73,22 @@ API Reference
 Plugin defenition
 ~~~~~~~~~~~~~~~~~
 
+.. automodule:: returns.contrib.mypy._consts
+   :members:
+
 .. autoclasstree:: returns.contrib.mypy.returns_plugin
 
 .. automodule:: returns.contrib.mypy.returns_plugin
    :members:
 
+Kind
+~~~~
+
+.. autoclasstree:: returns.contrib.mypy._features.kind
+
+.. automodule:: returns.contrib.mypy._features.kind
+   :members:
+
 Curry
 ~~~~~
 
@@ -100,19 +113,18 @@ Flow
 .. automodule:: returns.contrib.mypy._features.flow
    :members:
 
-Decorators
-~~~~~~~~~~
+Pipe
+~~~~
 
-.. autoclasstree:: returns.contrib.mypy._features.decorators
+.. autoclasstree:: returns.contrib.mypy._features.pipe
 
-.. automodule:: returns.contrib.mypy._features.decorators
+.. automodule:: returns.contrib.mypy._features.pipe
    :members:
 
+Decorators
+~~~~~~~~~~
 
-Pointfree
-~~~~~~~~~
-
-.. autoclasstree:: returns.contrib.mypy._features.pointfree
+.. autoclasstree:: returns.contrib.mypy._features.decorators
 
-.. automodule:: returns.contrib.mypy._features.pointfree
+.. automodule:: returns.contrib.mypy._features.decorators
    :members:

docs/pages/hkt.rst

@@ -0,0 +1,10 @@
+.. _hkt:
+
+Higher Kinded Types
+===================
+
+API Reference
+-------------
+
+.. automodule:: returns.primitives.hkt
+  :members: