WIP

Author: sobolevn

CHANGELOG.md

@@ -7,6 +7,7 @@ We follow Semantic Versions since the `0.1.0` release.
 
 ### Features
 
+- Adds support for concrete generic types like `List[str]` and `Set[int]` #24
 - Adds support for multiple type arguments in `Supports` type #244
 - Adds support for types that have `__instancecheck__` defined #248
 

classes/_registry.py

@@ -0,0 +1,40 @@
+from types import MethodType
+from typing import Callable, Dict, NoReturn, Optional
+
+TypeRegistry = Dict[type, Callable]
+
+
+def choose_registry(  # noqa: WPS211
+    # It has multiple argumnets, but I don't see an easy and performant way
+    # to refactor it: I don't want to create extra structures
+    # and I don't want to create a class with methods.
+    typ: type,
+    is_protocol: bool,
+    delegate: Optional[type],
+    concretes: TypeRegistry,
+    instances: TypeRegistry,
+    protocols: TypeRegistry,
+) -> TypeRegistry:
+    """"""
+    if is_protocol:
+        return protocols
+
+    is_concrete = (
+        delegate is not None or
+        isinstance(getattr(typ, '__instancecheck__', None), MethodType)
+    )
+    if is_concrete:
+        # This means that this type has `__instancecheck__` defined,
+        # which allows dynamic checks of what `isinstance` of this type.
+        # That's why we also treat this type as a conrete.
+        return concretes
+    return instances
+
+
+def default_implementation(instance, *args, **kwargs) -> NoReturn:
+    """By default raises an exception."""
+    raise NotImplementedError(
+        'Missing matched typeclass instance for type: {0}'.format(
+            type(instance).__qualname__,
+        ),
+    )

classes/_typeclass.py

@@ -134,6 +134,12 @@
 
 from typing_extensions import TypeGuard, final
 
+from classes._registry import (
+    TypeRegistry,
+    choose_registry,
+    default_implementation,
+)
+
 _InstanceType = TypeVar('_InstanceType')
 _SignatureType = TypeVar('_SignatureType', bound=Callable)
 _AssociatedType = TypeVar('_AssociatedType')
@@ -305,12 +311,17 @@ class _TypeClass(  # noqa: WPS214
     """
 
     __slots__ = (
+        # Str:
         '_signature',
         '_associated_type',
+
+        # Registry:
+        '_concretes',
         '_instances',
         '_protocols',
+
+        # Cache:
         '_dispatch_cache',
-        '_cache_token',
     )
 
     _dispatch_cache: Dict[type, Callable]
@@ -349,16 +360,17 @@ def __init__(
           The only exception is the first argument: it is polymorfic.
 
         """
-        self._instances: Dict[type, Callable] = {}
-        self._protocols: Dict[type, Callable] = {}
-
         # We need this for `repr`:
         self._signature = signature
         self._associated_type = associated_type
 
+        # Registries:
+        self._concretes: TypeRegistry = {}
+        self._instances: TypeRegistry = {}
+        self._protocols: TypeRegistry = {}
+
         # Cache parts:
         self._dispatch_cache = WeakKeyDictionary()  # type: ignore
-        self._cache_token = None
 
     def __call__(
         self,
@@ -410,16 +422,25 @@ def __call__(
         And all typeclasses that match ``Callable[[int, int], int]`` signature
         will typecheck.
         """
-        self._control_abc_cache()
+        # At first, we try all our conrete types,
+        # we don't cache it, because we cannot.
+        # We only have runtime type info: `type([1]) == type(['a'])`.
+        # It might be slow!
+        # Don't add concrete types unless
+        # you are absolutely know what you are doing.
+        impl = self._dispatch_concrete(instance)
+        if impl is not None:
+            return impl(instance, *args, **kwargs)
+
         instance_type = type(instance)
 
         try:
             impl = self._dispatch_cache[instance_type]
         except KeyError:
-            impl = self._dispatch(  # TODO: impl, store_cache = self._dispatch
+            impl = self._dispatch(
                 instance,
                 instance_type,
-            ) or self._default_implementation
+            ) or default_implementation
             self._dispatch_cache[instance_type] = impl
         return impl(instance, *args, **kwargs)
 
@@ -481,16 +502,24 @@ def supports(
 
         See also: https://www.python.org/dev/peps/pep-0647
         """
-        self._control_abc_cache()
-
+        # Here we first check that instance is already in the cache
+        # and only then we check concrete types.
+        # Why?
+        # Because if some type is already in the cache,
+        # it means that it is not concrete.
+        # So, this is simply faster.
         instance_type = type(instance)
         if instance_type in self._dispatch_cache:
             return True
 
-        # This only happens when we don't have a cache in place:
+        # We never cache concrete types.
+        if self._dispatch_concrete(instance) is not None:
+            return True
+
+        # This only happens when we don't have a cache in place
+        # and this is not a concrete generic:
         impl = self._dispatch(instance, instance_type)
         if impl is None:
-            self._dispatch_cache[instance_type] = self._default_implementation
             return False
 
         self._dispatch_cache[instance_type] = impl
@@ -541,35 +570,21 @@ def instance(
         isinstance(object(), typ)
 
         def decorator(implementation):
-            container = self._protocols if is_protocol else self._instances
+            container = choose_registry(
+                typ=typ,
+                is_protocol=is_protocol,
+                delegate=delegate,
+                concretes=self._concretes,
+                instances=self._instances,
+                protocols=self._protocols,
+            )
             container[typ] = implementation
 
-            if isinstance(getattr(typ, '__instancecheck__', None), MethodType):
-                # This means that this type has `__instancecheck__` defined,
-                # which allows dynamic checks of what `isinstance` of this type.
-                # That's why we also treat this type as a protocol.
-                self._protocols[typ] = implementation
-
-            if self._cache_token is None:  # pragma: no cover
-                if getattr(typ, '__abstractmethods__', None):
-                    self._cache_token = get_cache_token()
             self._dispatch_cache.clear()
             return implementation
 
         return decorator
 
-    def _control_abc_cache(self) -> None:
-        """
-        Required to drop cache if ``abc`` type got new subtypes in runtime.
-
-        Copied from ``cpython``.
-        """
-        if self._cache_token is not None:
-            current_token = get_cache_token()
-            if self._cache_token != current_token:
-                self._dispatch_cache.clear()
-                self._cache_token = current_token
-
     def _dispatch(self, instance, instance_type: type) -> Optional[Callable]:
         """
         Dispatches a function by its type.
@@ -589,13 +604,11 @@ def _dispatch(self, instance, instance_type: type) -> Optional[Callable]:
 
         return _find_impl(instance_type, self._instances)
 
-    def _default_implementation(self, instance, *args, **kwargs) -> NoReturn:
-        """By default raises an exception."""
-        raise NotImplementedError(
-            'Missing matched typeclass instance for type: {0}'.format(
-                type(instance).__qualname__,
-            ),
-        )
+    def _dispatch_concrete(self, instance) -> Optional[Callable]:
+        for concrete, callback in self._concretes.items():
+            if isinstance(instance, concrete):
+                return callback
+        return None
 
 
 if TYPE_CHECKING:

docs/pages/api-docs.rst

@@ -1,6 +1,12 @@
 Typeclass
 =========
 
+Caching
+-------
+
+API
+---
+
 Here are the technical docs about ``typeclass`` and how to use it.
 
 .. automodule:: classes._typeclass

docs/pages/concept.rst

@@ -142,6 +142,19 @@ 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
 ---------
@@ -168,8 +181,9 @@ We need some custom type inference mechanism:
   >>> class _ListOfIntMeta(type):
   ...     def __instancecheck__(self, arg) -> bool:
   ...         return (
-  ...             isinstance(other, list) and
-  ...             all(isinstance(item, int) for item in arg
+  ...             isinstance(arg, list) and
+  ...             bool(arg) and  # we need to have at least one `int` element
+  ...             all(isinstance(item, int) for item in arg)
   ...         )
 
   >>> class ListOfInt(List[int], metaclass=_ListOfIntMeta):
@@ -198,7 +212,7 @@ And now we can use it with ``classes``:
 
   >>> your_list = [1, 2, 3]
   >>> if isinstance(your_list, ListOfInt):
-  ...     sum_all(your_list)
+  ...     assert sum_all(your_list) == 6
 
 This solution still has several problems:
 
@@ -219,21 +233,30 @@ First, you need to define a "phantom" type
 .. code:: python
 
   >>> from phantom import Phantom
-  >>> from phantom.predicates import collection, generic
+  >>> from phantom.predicates import boolean, collection, generic, numeric
 
   >>> class ListOfInt(
   ...    List[int],
   ...    Phantom,
-  ...    predicate=collection.every(generic.of_type(int)),
+  ...    predicate=boolean.both(
+  ...       collection.count(numeric.greater(0)),
+  ...       collection.every(generic.of_type(int)),
+  ...    ),
   ... ):
   ...     ...
 
   >>> assert isinstance([1, 2, 3], ListOfInt)
   >>> assert type([1, 2, 3]) is list
 
-Short, easy, and readable.
+Short, easy, and readable:
+
+- By defining ``predicate`` we ensure
+  that all non-empty lists with ``int`` elements
+  will be treated as ``ListOfInt``
+- In runtime ``ListOfInt`` does not exist, because it is phantom!
+  In reality it is just ``List[int]``
 
-Now, we can define our typeclass with "phantom" type support:
+Now, we can define our typeclass with ``phantom`` type support:
 
 .. code:: python
 
@@ -272,15 +295,18 @@ Type resolution order
 
 Here's how typeclass resolve types:
 
-1. We try to resolve exact match by a passed type
-2. Then we try to match passed type with ``isinstance``
-   against types that support it, like protocols and delegates,
+1. At first we try to resolve types via delegates and ``isinstance`` checks
+2. We try to resolve exact match by a passed type
+3. Then we try to match passed type with ``isinstance``
+   against protocol types,
    first match wins
-3. Then we traverse ``mro`` entries of a given type,
+4. Then we traverse ``mro`` entries of a given type,
    looking for ones we can handle,
    first match wins
 
-We use cache, so calling typeclasses with same object types is fast.
+We use cache for all parts of algorithm except the first step
+(it is never cached),
+so calling typeclasses with same object types is fast.
 
 In other words, it can fallback to more common types:
 

tests/conftest.py

@@ -0,0 +1,13 @@
+import pytest
+from contextlib import contextmanager
+
+
+@pytest.fixture(scope='session')
+def clear_cache():
+    """Fixture to clear typeclass'es cache before and after."""
+    @contextmanager
+    def factory(typeclass):
+        typeclass._dispatch_cache.clear()  # noqa: WPS437
+        yield
+        typeclass._dispatch_cache.clear()  # noqa: WPS437
+    return factory