Renames .rescue to .lash (#671)

* Renames .rescue to .lash

* Fixes docs

* Fixes typesafety tests

* Improves docs

* Refs #674

* Refs #674

* Adds docs on how to create your own container

* Fixes CI

Author: sobolevn

CHANGELOG.md

@@ -17,6 +17,7 @@ See [0Ver](https://0ver.org/).
 - **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**: renames `.rescue` to `.lash`
 - **Breaking**: removes all old interfaces from `primitives/interfaces.py`,
   use new typeclasses instead
 - **Breaking**: ``Maybe`` is fully reworked to be lawful
@@ -88,7 +89,9 @@ See [0Ver](https://0ver.org/).
 - Adds a lot of new typetests
 - Checks that now all math laws are checked for all types
 - Changes docs structure, adds new `Interfaces`, `HKT`, and `Methods` pages
-- Changed str function in BaseContainer class to repr function.  
+- Changed `__str__` method in `BaseContainer` class to `__repr__` method
+- Adds `Quickstart` guide
+
 
 ## 0.14.0
 

docs/pages/contrib/pytest_plugins.rst

@@ -44,7 +44,7 @@ It tests that containers do handle error track.
   def test_my_container(returns):
       assert not returns.is_error_handled(Failure(1))
       assert returns.is_error_handled(
-          Failure(1).rescue(lambda _: Success('default value')),
+          Failure(1).lash(lambda _: Success('default value')),
       )
 
 We recommed to unit test big chunks of code this way.
@@ -53,7 +53,7 @@ you need at least one error handling at the very end.
 
 This is how it works internally:
 
-- Methods like ``fix`` and ``rescue`` mark errors
+- Methods like ``fix`` and ``lash`` mark errors
   inside the container as handled
 - Methods like ``map`` and ``alt`` just copies
   the error handling state from the old container to a new one,

docs/pages/create-your-own-container.rst

@@ -30,6 +30,9 @@ What is a ``Pair``? Well, it is literally a pair of two values.
 No more, no less. Similar to a ``Tuple[FirstType, SecondType]``.
 But with extra goodies.
 
+.. note::
+  You can find all `code samples here <https://github.com/dry-python/returns/tree/master/tests/test_examples>`_.
+
 
 Step 1: Choosing right interfaces
 ---------------------------------
@@ -52,19 +55,16 @@ And then subtype the interfaces that provide these methods and laws.
 
 What interfaces a ``Pair`` type needs?
 
-- :class:`returns.interfaces.equable.SupportsEquality`,
+- :class:`returns.interfaces.equable.Equable`,
   because two ``Pair`` instances can be compared
 - :class:`returns.interfaces.mappable.MappableN`,
   because the first type can be composed with pure functions
 - :class:`returns.interfaces.bindable.BindableN`,
   because a ``Pair`` can be bound to a function returning a new ``Pair``
   based on the first type
-- :class:`returns.interfaces.applicative.ApplicativeN`,
-  because you can construct new ``Piar`` from a value
-  and apply a wrapped function over it
 - :class:`returns.interfaces.altable.AltableN`,
   because the second type can be composed with pure functions
-- :class:`returns.interfaces.rescuable.RescuableN`,
+- :class:`returns.interfaces.lashable.LashableN`,
   because a ``Pair`` can be bound to a function returning a new ``Pair``
   based on the second type
 
@@ -74,9 +74,8 @@ let's find pre-defined aliases we can reuse.
 Turns out, there are some of them!
 
 - :class:`returns.interfaces.bimappable.BiMappableN`
-  which combines ``MappableN`` and ``AltableN``
-- :class:`returns.interfaces.container.ContainerN` which combines
-  ``ApplicativeN`` and ``BindableN``
+  which combines ``MappableN`` and ``AltableN``,
+  it also requires to add a new method called ``.swap`` to change values order
 
 Let's look at the resul:
 
@@ -85,8 +84,8 @@ Let's look at the resul:
   >>> from typing_extensions import final
   >>> from typing import Callable, TypeVar, Tuple
 
-  >>> from returns.interfaces import container, bimappable, rescuable, equable
-  >>> from returns.primitives.container import BaseContainer, container_equality
+  >>> from returns.interfaces import bimappable, bindable, equable, lashable
+  >>> from returns.primitives.container import BaseContainer
   >>> from returns.primitives.hkt import SupportsKind2
 
   >>> _FirstType = TypeVar('_FirstType')
@@ -99,10 +98,10 @@ Let's look at the resul:
   ... class Pair(
   ...     BaseContainer,
   ...     SupportsKind2['Pair', _FirstType, _SecondType],
-  ...     container.Container2[_FirstType, _SecondType],
+  ...     bindable.Bindable2[_FirstType, _SecondType],
   ...     bimappable.BiMappable2[_FirstType, _SecondType],
-  ...     rescuable.Rescuable2[_FirstType, _SecondType],
-  ...     equable.SupportsEquality,
+  ...     lashable.Lashable2[_FirstType, _SecondType],
+  ...     equable.Equable,
   ... ):
   ...     def __init__(
   ...         self, inner_value: Tuple[_FirstType, _SecondType],
@@ -119,36 +118,171 @@ Let's look at the resul:
 Later we will talk about an actual implementation of all required methods.
 
 
-Step 2: Defining new interfaces and associated laws
----------------------------------------------------
+Step 2: Initial implementation
+------------------------------
+
+So, let's start writting some code!
+
+We would need to implement all interface methods,
+otherwise ``mypy`` won't be happy.
+That's what it currently says on our type definition:
+
+.. code::
+
+  error: Final class test_pair1.Pair has abstract attributes "alt", "bind", "equals", "lash", "map", "swap"
+
+Looks like it already knows what methods should be there!
+
+Ok, let's drop some initial and straight forward implementation.
+We will later make it more complex step by step.
+
+.. literalinclude:: ../../tests/test_examples/test_pair1.py
+   :linenos:
+
+You can check our resulting source with ``mypy``. It would be happy this time.
+
+
+Step 3: New interfaces
+----------------------
+
+As you can see our existing interfaces do not cover everything.
+We can potentially want several extra things:
 
-After the initial analysis in the "Step 1",
-you can decide to introduce your own methods.
+1. A method that takes two arguments and returns a new ``Pair`` instance
+2. A named constructor to create a ``Pair`` from a single value
+3. A named constructor to create a ``Pair`` from two values
 
-These methods can probably form an interface,
-if you want to make generic utilities for your type.
+We can define an interface just for this!
+It would be also nice to add all other interfaces there as supertypes.
 
-Let's say your type will have ``.from_tuple`` and ``.replace`` methods,
-that can look like so:
+That's how it is going to look:
 
+.. literalinclude:: ../../tests/test_examples/test_pair2.py
+   :linenos:
+   :pyobject: PairLikeN
 
+Awesome! Now we have a new interface to implement. Let's do that!
 
+.. literalinclude:: ../../tests/test_examples/test_pair2.py
+   :linenos:
+   :pyobject: Pair.pair
 
-Step 3: Actual implementation
------------------------------
+.. literalinclude:: ../../tests/test_examples/test_pair2.py
+   :linenos:
+   :pyobject: Pair.from_unpaired
+
+Looks like we are done!
 
 
 Step 4: Writting tests and docs
 -------------------------------
 
+The best part about this type is that it is pure.
+So, we can write our tests inside docs!
 
-Step 5: Writting type-tests
----------------------------
+We are going to use
+`doctests <https://docs.python.org/3/library/doctest.html>`_
+builtin module for that.
+
+This gives us several key benefits:
+
+- All our docs has usage examples
+- All our examples are correct, because they are executed and tested
+- We don't need to write regular boring tests
+
+Let's add docs and doctests! Let's use ``map`` method as a short example:
+
+.. literalinclude:: ../../tests/test_examples/test_pair3.py
+   :linenos:
+   :pyobject: Pair.map
 
+By adding these simple tests we would already have 100% coverage.
+But, what if we can completely skip writting tests, but still have 100%?
 
-Step 6: Checking laws
+Let's discuss how we can achieve that with "Laws as values".
+
+
+Step 5: Checking laws
 ---------------------
 
+We already ship lots of laws with our interfaces.
+See our docs on :ref:`laws and checking them <hypothesis-plugins>`.
+
+Moreover, you can also define your own laws!
+Let's add them to our ``PairLikeN`` interface.
+
+Let's start with laws definition:
+
+.. literalinclude:: ../../tests/test_examples/test_pair4.py
+   :linenos:
+   :pyobject: _LawSpec
+
+And them let's add them to our ``PairLikeN`` interface:
+
+.. literalinclude:: ../../tests/test_examples/test_pair4.py
+   :linenos:
+   :pyobject: PairLikeN
+   :emphasize-lines: 9-12
+
+The last to do is to call ``check_all_laws(Pair, use_init=True)``
+to generate 10 ``hypothesis`` test cases with hundreds real test cases inside.
+
+Here's the final result of our brand new ``Pair`` type:
+
+.. literalinclude:: ../../tests/test_examples/test_pair4.py
+   :linenos:
+
+
+Step 6: Writting type-tests
+---------------------------
+
+.. note::
+    You can find all `type-tests here <https://github.com/dry-python/returns/tree/master/typesafety/test_examples>`_.
+
+The next thing we want is to write a type-test!
+
+What is a type-test? This is a special type of tests for your typing.
+We run ``mypy`` on top of tests and use snapshots to assert the result.
+
+We recommend to use `pytest-mypy-plugins <https://github.com/typeddjango/pytest-mypy-plugins>`_.
+`Read more <https://sobolevn.me/2019/08/testing-mypy-types>`_
+about how to use it.
+
+Let's start with a simple test
+to make sure our ``.pair`` function works correctly:
+
+.. warning::
+  Please, don't use ``env:`` property the way we do here.
+  We need it since we store our example in ``tests/`` folder.
+  And we have to tell ``mypy`` how to find it.
+
+.. literalinclude:: ../../typesafety/test_examples/test_pair4_def.yml
+   :linenos:
+
+Ok, now, let's try to raise an error by using it incorrectly:
+
+.. literalinclude:: ../../typesafety/test_examples/test_pair4_error.yml
+   :linenos:
+
 
 Step 7: Reusing code
 --------------------
+
+The last (but not the least!) thing you need
+to know is that you can reuse all code
+we already have for this new ``Pair`` type.
+
+This is because of our :ref:`hkt` feature.
+
+So, let's say we want to use native :func:`~returns.pointfree.map.map_`
+pointfree function with our new ``Pair`` type.
+Let's test that it will work correctly:
+
+.. literalinclude:: ../../typesafety/test_examples/test_pair4_reuse.yml
+   :linenos:
+
+Yes, it works!
+
+Now you have fully working, typed, documented, lawful, and tested primitive.
+You can build any other primitive
+you need for your business logic or infrastructure.

docs/pages/interfaces.rst

@@ -62,8 +62,9 @@ We follow a very specific naming convention in our interface names.
 
 If interface does not depend on the number of types
 it works with and is always the same, we name it as is.
-For example, ``SupportsEquality`` is always the same
+For example, ``Equable`` is always the same
 and does not depend on the number of type arguments.
+We use adjectives to name these interfaces.
 
 Secondly, if interface depends on the number of type arguments,
 it is named with ``N`` suffix in the end.
@@ -81,7 +82,7 @@ Laws
 ~~~~
 
 Some interfaces define its laws as values.
-These laws can be viewed as test that are attached to an interface.
+These laws can be viewed as tests that are attached to the specific interface.
 
 We are able to check them of any type
 that implements a given interfaces with laws
@@ -447,7 +448,7 @@ Here's a full overview of all our interfaces:
    returns.interfaces.mappable
    returns.interfaces.bindable
    returns.interfaces.applicative
-   returns.interfaces.rescuable
+   returns.interfaces.lashable
    returns.interfaces.altable
    returns.interfaces.bimappable
    returns.interfaces.unwrappable
@@ -467,8 +468,8 @@ Here's a full overview of all our interfaces:
 
 Let's review it one by one.
 
-SupportsEquality
-~~~~~~~~~~~~~~~~
+Equable
+~~~~~~~
 
 .. autoclasstree:: returns.interfaces.equable
    :strict:
@@ -527,13 +528,13 @@ BiMappable
   :members:
   :private-members:
 
-Rescuable
-~~~~~~~~~
+Lashable
+~~~~~~~~
 
-.. autoclasstree:: returns.interfaces.rescuable
+.. autoclasstree:: returns.interfaces.lashable
    :strict:
 
-.. automodule:: returns.interfaces.rescuable
+.. automodule:: returns.interfaces.lashable
   :members:
   :private-members:
 

docs/pages/pointfree.rst

@@ -119,27 +119,27 @@ We also have a long list of other ``bind_*`` functions, like:
 - ``bind_awaitable`` to bind async non-container functions
 
 
-rescue
-------
+lash
+----
 
-Pointfree ``rescue()`` function is an alternative
-to ``.rescue()`` container method.
+Pointfree ``lash()`` function is an alternative
+to ``.lash()`` container method.
 It is also required for better declarative programming.
 
 .. code:: python
 
-  >>> from returns.pointfree import rescue
+  >>> from returns.pointfree import lash
   >>> from returns.result import Success, Failure, Result
 
   >>> def function(arg: str) -> Result[int, str]:
   ...     return Success(1)
 
   >>> container: Result[int, str] = Failure('a')
   >>> # We now have two way of composining these entities.
-  >>> # 1. Via ``.rescue``:
-  >>> assert container.rescue(function) == Success(1)
-  >>> # 2. Or via ``rescue`` function, the same but in the inverse way:
-  >>> assert rescue(function)(container) == Success(1)
+  >>> # 1. Via ``.lash``:
+  >>> assert container.lash(function) == Success(1)
+  >>> # 2. Or via ``lash`` function, the same but in the inverse way:
+  >>> assert lash(function)(container) == Success(1)
 
 
 apply
@@ -318,7 +318,7 @@ API Reference
 
 .. autofunction:: returns.pointfree.cond
 
-.. autofunction:: returns.pointfree.rescue
+.. autofunction:: returns.pointfree.lash
 
 .. autofunction:: returns.pointfree.unify