Finishes with delegates

Author: sobolevn

classes/_typeclass.py

@@ -534,9 +534,9 @@ def instance(
         We use this method to store implementation for each specific type.
 
         Args:
-            is_protocol - required when passing protocols.
-            delegate - required when using delegate types, for example,
-                when working with concrete generics like ``List[str]``.
+            is_protocol: required when passing protocols.
+            delegate: required when using delegate types, for example,
+            when working with concrete generics like ``List[str]``.
 
         Returns:
             Decorator for instance handler.

classes/contrib/mypy/typeops/instance_context.py

@@ -156,7 +156,7 @@ def _infer_instance_type(
         def _some_list(instance: list) -> int:
             ...
 
-    Then, infered instance type is just ``list``.
+    Then, inferred instance type is just ``list``.
 
     Second, we have a delegate of its own:
 
@@ -166,7 +166,7 @@ def _some_list(instance: list) -> int:
         def _some_list(instance: list) -> int:
             ...
 
-    Then, infered instance type is ``list`` as well.
+    Then, inferred instance type is ``list`` as well.
 
     Lastly, we can have this case,
     when ``delegate`` type is used for instance annotation:

docs/conf.py

@@ -15,8 +15,6 @@
 import os
 import sys
 
-import sphinx
-
 sys.path.insert(0, os.path.abspath('..'))
 
 

docs/pages/concept.rst

@@ -95,67 +95,6 @@ to be specified on ``.instance()`` call:
   >>> assert to_json([1, 'a', None]) == '[1, "a", null]'
 
 
-``__instancecheck__`` magic method
-----------------------------------
-
-We also support types that have ``__instancecheck__`` magic method defined,
-like `phantom-types <https://github.com/antonagestam/phantom-types>`_.
-
-We treat them similar to ``Protocol`` types, by checking passed values
-with ``isinstance`` for each type with ``__instancecheck__`` defined.
-First match wins.
-
-Example:
-
-.. code:: python
-
-  >>> from classes import typeclass
-
-  >>> class Meta(type):
-  ...     def __instancecheck__(self, other) -> bool:
-  ...         return other == 1
-
-  >>> class Some(object, metaclass=Meta):
-  ...     ...
-
-  >>> @typeclass
-  ... def some(instance) -> int:
-  ...     ...
-
-  >>> @some.instance(Some)
-  ... def _some_some(instance: Some) -> int:
-  ...     return 2
-
-  >>> argument = 1
-  >>> assert isinstance(argument, Some)
-  >>> assert some(argument) == 2
-
-.. warning::
-
-  It is impossible for ``mypy`` to understand that ``1`` has ``Some``
-  type in this example. Be careful, it might break your code!
-
-This example is not really useful on its own,
-because as it was said, it can break things.
-
-Instead, we are going to learn about
-how this feature can be used to model
-your domain model precisely with delegates.
-
-Performance considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Types that are matched via ``__instancecheck__`` are the first one we try.
-So, the worst case complexity of this is ``O(n)``
-where ``n`` is the number of types to try.
-
-We also always try them first and do not cache the result.
-This feature is here because we need to handle concrete generics.
-But, we recommend to think at least
-twice about the performance side of this feature.
-Maybe you can just write a function?
-
-
 Delegates
 ---------
 
@@ -172,6 +111,9 @@ that some ``list`` is ``List[int]`` or ``List[str]``:
     ...
   TypeError: Subscripted generics cannot be used with class and instance checks
 
+``__instancecheck__`` magic method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 We need some custom type inference mechanism:
 
 .. code:: python
@@ -197,40 +139,10 @@ Now we can be sure that our ``List[int]`` can be checked in runtime:
   >>> assert isinstance([1, 'a'], ListOfInt) is False
   >>> assert isinstance([], ListOfInt) is False  # empty
 
-And now we can use it with ``classes``:
+``delegate`` argument
+~~~~~~~~~~~~~~~~~~~~~
 
-.. code:: python
-
-  >>> from classes import typeclass
-
-  >>> @typeclass
-  ... def sum_all(instance) -> int:
-  ...     ...
-
-  >>> @sum_all.instance(ListOfInt)
-  ... def _sum_all_list_int(instance: ListOfInt) -> int:
-  ...     return sum(instance)
-
-  >>> your_list = [1, 2, 3]
-  >>> if isinstance(your_list, ListOfInt):
-  ...     assert sum_all(your_list) == 6
-
-This solution still has several problems:
-
-1. Notice, that you have to use ``if isinstance`` or ``assert isinstance`` here.
-   Because otherwise ``mypy`` won't be happy without it,
-   type won't be narrowed to ``ListOfInt`` from ``List[int]``.
-   This does not feel right.
-2. ``ListOfInt`` is very verbose, it even has a metaclass!
-3. There's a typing mismatch: in runtime ``your_list`` would be ``List[int]``
-   and ``mypy`` thinks that it is ``ListOfInt``
-   (a fake type that we are not ever using directly)
-
-delegate argument
-~~~~~~~~~~~~~~~~~
-
-To solve the first problem,
-we can use ``delegate=`` argument to ``.instance`` call:
+And now we can use it with ``classes``:
 
 .. code:: python
 
@@ -252,8 +164,8 @@ What happens here? When defining an instance with ``delegate`` argument,
 what we really do is: we add our ``delegate``
 into a special registry inside ``sum_all`` typeclass.
 
-This registry is using ``isinstance``
-to find handler that fit the defined predicate.
+This registry is using ``isinstance`` function
+to find handler that fits the defined predicate.
 It has the highest priority among other dispatch methods.
 
 This allows to sync both runtime and ``mypy`` behavior:
@@ -271,9 +183,9 @@ This allows to sync both runtime and ``mypy`` behavior:
 Phantom types
 ~~~~~~~~~~~~~
 
-To solve problems ``2`` and ``3`` we recommend to use ``phantom-types`` package.
+Notice, that ``ListOfInt`` is very verbose, it even has an explicit metaclass!
 
-First, you need to define a "phantom" type
+There's a better way, you need to define a "phantom" type
 (it is called "phantom" because it does not exist in runtime):
 
 .. code:: python
@@ -306,6 +218,19 @@ Now, we can define our typeclass with ``phantom`` type support:
 
 .. code:: python
 
+  >>> from phantom import Phantom
+  >>> from phantom.predicates import boolean, collection, generic, numeric
+
+  >>> class ListOfInt(
+  ...    List[int],
+  ...    Phantom,
+  ...    predicate=boolean.both(
+  ...       collection.count(numeric.greater(0)),
+  ...       collection.every(generic.of_type(int)),
+  ...    ),
+  ... ):
+  ...     ...
+
   >>> from classes import typeclass
 
   >>> @typeclass
@@ -325,8 +250,12 @@ we delegate all the runtime type checking to ``ListOfInt`` phantom type.
 Performance considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Types that are matched via ``__instancecheck__`` are the first one we try.
 Traversing the whole list to check that all elements
 are of the given type can be really slow.
+The worst case complexity of this is ``O(n)``
+where ``n`` is the number of types to try.
+We also always try them first and do not cache the result.
 
 You might need a different algorithm.
 Take a look at `beartype <https://github.com/beartype/beartype>`_.
@@ -335,13 +264,17 @@ with negligible constant factors.
 
 Take a look at their docs to learn more.
 
+We recommend to think at least
+twice about the performance side of this feature.
+Maybe you can just write a function?
+
 
 Type resolution order
 ---------------------
 
 Here's how typeclass resolve types:
 
-1. At first we try to resolve types via delegates and ``isinstance`` checks
+1. At first we try to resolve types via delegates and ``isinstance`` check
 2. We try to resolve exact match by a passed type
 3. Then we try to match passed type with ``isinstance``
    against protocol types,

docs/pages/supports.rst

@@ -6,6 +6,13 @@ Supports
 We also have a special type to help you specifying
 that you want to work with only types that are a part of a specific typeclass.
 
+.. warning::
+  ``Supports`` only works with typeclasses defined with associated types.
+
+
+Regular types
+-------------
+
 For example, you might want to work with only types
 that are able to be converted to JSON.
 
@@ -51,6 +58,10 @@ And this will fail (both in runtime and during type checking):
       ...
     NotImplementedError: Missing matched typeclass instance for type: NoneType
 
+
+Supports for instance annotations
+---------------------------------
+
 You can also use ``Supports`` as a type annotation for defining typeclasses:
 
 .. code:: python
@@ -74,5 +85,103 @@ One more tip, our team would recommend this style:
     ... class MyFeature(AssociatedType):
     ...     """Tell us, what this typeclass is about."""
 
-.. warning::
-  ``Supports`` only works with typeclasses defined with associated types.
+
+Supports and delegates
+----------------------
+
+``Supports`` type has a special handling of ``delegate`` types.
+Let's see an example. We would start with defining a ``delegate`` type:
+
+.. code:: python
+
+  >>> from typing import List
+  >>> from classes import AssociatedType, Supports, typeclass
+
+  >>> class ListOfIntMeta(type):
+  ...     def __instancecheck__(cls, arg) -> bool:
+  ...         return (
+  ...             isinstance(arg, list) and
+  ...             bool(arg) and
+  ...             all(isinstance(list_item, int) for list_item in arg)
+  ...         )
+
+  >>> class ListOfInt(List[int], metaclass=ListOfIntMeta):
+  ...     ...
+
+Now, let's define a typeclass:
+
+.. code:: python
+
+  >>> class SumAll(AssociatedType):
+  ...     ...
+
+  >>> @typeclass(SumAll)
+  ... def sum_all(instance) -> int:
+  ...     ...
+
+  >>> @sum_all.instance(List[int], delegate=ListOfInt)
+  ... def _sum_all_list_int(
+  ...     # It can be either `List[int]` or `ListOfInt`
+  ...     instance: List[int],
+  ... ) -> int:
+  ...     return sum(instance)
+
+And a function with ``Supports`` type:
+
+.. code:: python
+
+  >>> def test(to_sum: Supports[SumAll]) -> int:
+  ...     return sum_all(to_sum)
+
+This will not make ``mypy`` happy:
+
+.. code:: python
+
+  >>> list1 = [1, 2, 3]
+  >>> assert test(list1) == 6  # Argument 1 to "test" has incompatible type "List[int]"; expected "Supports[SumAll]"
+
+It will be treated the same as unsupported cases, like ``List[str]``:
+
+.. code:: python
+
+  list2: List[str]
+  test(list2)  # Argument 1 to "test" has incompatible type "List[int]"; expected "Supports[SumAll]"
+
+But, this will work correctly:
+
+.. code:: python
+
+  >>> list_of_int = ListOfInt([1, 2, 3])
+  >>> assert test(list_of_int) == 6  # ok
+
+  >>> list1 = [1, 2, 3]
+  >>> if isinstance(list1, ListOfInt):
+  ...     assert test(list1) == 6  # ok
+
+This happens because we don't treat ``List[int]`` as ``Supports[SumAll]``.
+This is by design.
+
+But, we treat ``ListOfInt`` as ``Supports[SumAll]``.
+So, you would need to narrow ``List[int]`` to ``ListOfInt`` to make it work.
+
+General cases
+~~~~~~~~~~~~~
+
+One way to make ``List[int]`` to work without explicit type narrowing
+is to define a generic case for all ``list`` subtypes:
+
+.. code:: python
+
+  >>> @sum_all.instance(list)
+  ... def _sum_all_list(instance: list) -> int:
+  ...     return 0
+
+Now, this will work:
+
+.. code:: python
+
+  >>> list1 = [1, 2, 3]
+  >>> assert test(list1) == 6  # ok
+
+  >>> list2 = ['a', 'b']
+  >>> assert test(list2) == 0  # ok

tests/test_typeclass/test_cache.py

@@ -43,11 +43,11 @@ def test_cache_concrete(clear_cache) -> None:  # noqa: WPS218
         assert not my_typeclass._dispatch_cache  # noqa: WPS437
 
         assert my_typeclass(_MyConcrete()) == 1
-        assert not my_typeclass._dispatch_cache  # noqa: WPS437
+        assert _MyConcrete in my_typeclass._dispatch_cache  # noqa: WPS437
 
         _MyABC.register(_MyRegistered)
         assert my_typeclass(_MyRegistered()) == 2  # type: ignore
-        assert not my_typeclass._dispatch_cache  # noqa: WPS437
+        assert _MyRegistered in my_typeclass._dispatch_cache  # noqa: WPS437
 
 
 def test_cached_calls(clear_cache) -> None:

typesafety/test_typeclass/test_generics/test_generics_concrete.yml

@@ -89,7 +89,7 @@
     class ListOfIntMeta(type):
         def __instancecheck__(cls, arg) -> bool:
             return (
-                isinstance(cls, list) and
+                isinstance(arg, list) and
                 bool(arg) and
                 all(isinstance(list_item, int) for list_item in arg)
             )
@@ -131,7 +131,7 @@
     class ListOfIntMeta(type):
         def __instancecheck__(cls, arg) -> bool:
             return (
-                isinstance(cls, list) and
+                isinstance(arg, list) and
                 bool(arg) and
                 all(isinstance(list_item, int) for list_item in arg)
             )