Adds strict delegate types (#297)

* Adds strict delegate types

* Fixes CI

* Update supports.rst

* Update supports.rst

* Update supports.rst

* Update supports.rst

Author: sobolevn

classes/_registry.py

@@ -1,32 +1,48 @@
-from typing import Callable, Dict, NoReturn, Optional
+from typing import Callable, Dict, NoReturn, Optional, Tuple
+
+from typing_extensions import Final
 
 TypeRegistry = Dict[type, Callable]
 
+#: We use this to exclude `None` as a default value for `exact_type`.
+DefaultValue: Final = type('DefaultValueType', (object,), {})
+
+#: Used both in runtime and during mypy type-checking.
+INVALID_ARGUMENTS_MSG: Final = (
+    'Only a single argument can be applied to `.instance`'
+)
+
 
 def choose_registry(  # noqa: WPS211
     # It has multiple arguments, 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],
+    exact_type: Optional[type],
+    protocol: type,
+    delegate: type,
     delegates: TypeRegistry,
-    instances: TypeRegistry,
+    exact_types: TypeRegistry,
     protocols: TypeRegistry,
-) -> TypeRegistry:
+) -> Tuple[TypeRegistry, type]:
     """
     Returns the appropriate registry to store the passed type.
 
     It depends on how ``instance`` method is used and also on the type itself.
     """
-    if is_protocol and delegate is not None:
-        raise ValueError('Both `is_protocol` and `delegate` are passed')
+    passed_args = list(filter(
+        _is_not_default_argument_value,
+        (exact_type, protocol, delegate),
+    ))
+    if not passed_args:
+        raise ValueError('At least one argument to `.instance` is required')
+    if len(passed_args) > 1:
+        raise ValueError(INVALID_ARGUMENTS_MSG)
 
-    if is_protocol:
-        return protocols
-    elif delegate is not None:
-        return delegates
-    return instances
+    if _is_not_default_argument_value(delegate):
+        return delegates, delegate
+    elif _is_not_default_argument_value(protocol):
+        return protocols, protocol
+    return exact_types, exact_type if exact_type is not None else type(None)
 
 
 def default_implementation(instance, *args, **kwargs) -> NoReturn:
@@ -36,3 +52,7 @@ def default_implementation(instance, *args, **kwargs) -> NoReturn:
             type(instance).__qualname__,
         ),
     )
+
+
+def _is_not_default_argument_value(arg: Optional[type]) -> bool:
+    return arg is not DefaultValue

classes/_typeclass.py

@@ -72,13 +72,14 @@
 We also support protocols. It has the same limitation as ``Generic`` types.
 It is also dispatched after all regular instances are checked.
 
-To work with protocols, one needs to pass ``is_protocol`` flag to instance:
+To work with protocols, one needs
+to pass ``protocol`` named argument to instance:
 
 .. code:: python
 
     >>> from typing import Sequence
 
-    >>> @example.instance(Sequence, is_protocol=True)
+    >>> @example.instance(protocol=Sequence)
     ... def _sequence_example(instance: Sequence) -> str:
     ...     return ','.join(str(item) for item in instance)
 
@@ -99,7 +100,7 @@
     >>> class CustomProtocol(Protocol):
     ...     field: str
 
-    >>> @example.instance(CustomProtocol, is_protocol=True)
+    >>> @example.instance(protocol=CustomProtocol)
     ... def _custom_protocol_example(instance: CustomProtocol) -> str:
     ...     return instance.field
 
@@ -131,6 +132,7 @@
 from typing_extensions import TypeGuard, final
 
 from classes._registry import (
+    DefaultValue,
     TypeRegistry,
     choose_registry,
     default_implementation,
@@ -313,7 +315,7 @@ class _TypeClass(  # noqa: WPS214
 
         # Registry:
         '_delegates',
-        '_instances',
+        '_exact_types',
         '_protocols',
 
         # Cache:
@@ -362,7 +364,7 @@ def __init__(
 
         # Registries:
         self._delegates: TypeRegistry = {}
-        self._instances: TypeRegistry = {}
+        self._exact_types: TypeRegistry = {}
         self._protocols: TypeRegistry = {}
 
         # Cache parts:
@@ -382,8 +384,9 @@ def __call__(
 
         The resolution order is the following:
 
-        1. Exact types that are passed as ``.instance`` arguments
-        2. Protocols that are passed with ``is_protocol=True``
+        1. Delegates passed with ``delegate=``
+        2. Exact types that are passed as ``.instance`` arguments
+        3. Protocols that are passed with ``protocol=``
 
         We don't guarantee the order of types inside groups.
         Use correct types, do not rely on our order.
@@ -480,7 +483,7 @@ def supports(
 
           >>> from typing import Sized
 
-          >>> @example.instance(Sized, is_protocol=True)
+          >>> @example.instance(protocol=Sized)
           ... def _example_sized(instance: Sized) -> str:
           ...     return 'Size is {0}'.format(len(instance))
 
@@ -523,18 +526,16 @@ def supports(
 
     def instance(
         self,
-        type_argument: Optional[_NewInstanceType],
+        exact_type: Optional[_NewInstanceType] = DefaultValue,  # type: ignore
         *,
-        # TODO: at one point I would like to remove `is_protocol`
-        # and make this function decide whether this type is protocol or not.
-        is_protocol: bool = False,
-        delegate: Optional[type] = None,
+        protocol: type = DefaultValue,
+        delegate: type = DefaultValue,
     ) -> '_TypeClassInstanceDef[_NewInstanceType, _TypeClassType]':
         """
         We use this method to store implementation for each specific type.
 
         Args:
-            is_protocol: required when passing protocols.
+            protocol: required when passing protocols.
             delegate: required when using delegate types, for example,
             when working with concrete generics like ``List[str]``.
 
@@ -543,7 +544,8 @@ def instance(
 
         .. note::
 
-            ``is_protocol`` and ``delegate`` are mutually exclusive.
+            ``exact_type``, ``protocol``, and ``delegate``
+            are mutually exclusive. Only one argument can be passed.
 
         We don't use ``@overload`` decorator here
         (which makes our ``mypy`` plugin even more complex)
@@ -558,7 +560,14 @@ def instance(
         # Then, we have a regular `type_argument`. It is used for most types.
         # Lastly, we have `type(None)` to handle cases
         # when we want to register `None` as a type / singleton value.
-        typ = delegate or type_argument or type(None)
+        registry, typ = choose_registry(
+            exact_type=exact_type,
+            protocol=protocol,
+            delegate=delegate,
+            exact_types=self._exact_types,
+            protocols=self._protocols,
+            delegates=self._delegates,
+        )
 
         # That's how we check for generics,
         # generics that look like `List[int]` or `set[T]` will fail this check,
@@ -567,19 +576,9 @@ def instance(
         isinstance(object(), typ)
 
         def decorator(implementation):
-            container = choose_registry(
-                typ=typ,
-                is_protocol=is_protocol,
-                delegate=delegate,
-                delegates=self._delegates,
-                instances=self._instances,
-                protocols=self._protocols,
-            )
-            container[typ] = implementation
-
+            registry[typ] = implementation
             self._dispatch_cache.clear()
             return implementation
-
         return decorator
 
     def _dispatch(self, instance, instance_type: type) -> Optional[Callable]:
@@ -591,15 +590,15 @@ def _dispatch(self, instance, instance_type: type) -> Optional[Callable]:
         2. By matching protocols
         3. By its ``mro``
         """
-        implementation = self._instances.get(instance_type, None)
+        implementation = self._exact_types.get(instance_type, None)
         if implementation is not None:
             return implementation
 
         for protocol, callback in self._protocols.items():
             if isinstance(instance, protocol):
                 return callback
 
-        return _find_impl(instance_type, self._instances)
+        return _find_impl(instance_type, self._exact_types)
 
     def _dispatch_delegate(self, instance) -> Optional[Callable]:
         for delegate, callback in self._delegates.items():

classes/contrib/mypy/features/typeclass.py

@@ -17,7 +17,7 @@
 from classes.contrib.mypy.typeops import (
     call_signatures,
     fallback,
-    instance_args,
+    instance_type_args,
     mro,
     type_loader,
 )
@@ -78,7 +78,7 @@ def __call__(self, ctx: FunctionContext) -> MypyType:
             assert isinstance(defn, CallableType)
             assert defn.definition
 
-            instance_args.mutate_typeclass_def(
+            instance_type_args.mutate_typeclass_def(
                 typeclass=ctx.default_return_type,
                 definition_fullname=defn.definition.fullname,
                 ctx=ctx,
@@ -125,7 +125,7 @@ def __call__(self, ctx: MethodContext) -> MypyType:
         assert isinstance(ctx.default_return_type, Instance)
         assert isinstance(ctx.context, Decorator)
 
-        instance_args.mutate_typeclass_def(
+        instance_type_args.mutate_typeclass_def(
             typeclass=ctx.default_return_type,
             definition_fullname=ctx.context.func.fullname,
             ctx=ctx,
@@ -135,6 +135,7 @@ def __call__(self, ctx: MethodContext) -> MypyType:
             typeclass=ctx.default_return_type,
             ctx=ctx,
         )
+
         if isinstance(ctx.default_return_type.args[2], Instance):
             validate_associated_type.check_type(
                 associated_type=ctx.default_return_type.args[2],
@@ -161,7 +162,7 @@ def instance_return_type(ctx: MethodContext) -> MypyType:
         else:
             passed_types.append(UninhabitedType())
 
-    instance_args.mutate_typeclass_instance_def(
+    instance_type_args.mutate_typeclass_instance_def(
         ctx.default_return_type,
         ctx=ctx,
         typeclass=ctx.type,
@@ -237,12 +238,18 @@ def _load_typeclass(
         return typeclass, typeclass_ref.args[3].value
 
     def _run_validation(self, instance_context: InstanceContext) -> bool:
+        # When delegate is passed, we use it instead of instance type.
+        # Why? Because `delegate` can repre
+        instance_or_delegate = (
+            instance_context.inferred_args.delegate
+            if instance_context.inferred_args.delegate is not None
+            else instance_context.instance_type
+        )
         # We need to add `Supports` metadata before typechecking,
         # because it will affect type hierarchies.
         metadata = mro.MetadataInjector(
             associated_type=instance_context.associated_type,
-            instance_type=instance_context.instance_type,
-            delegate=instance_context.delegate,
+            instance_type=instance_or_delegate,
             ctx=instance_context.ctx,
         )
         metadata.add_supports_metadata()
@@ -262,7 +269,7 @@ def _add_new_instance_type(
         ctx: MethodContext,
     ) -> None:
         typeclass.args = (
-            instance_args.add_unique(new_type, typeclass.args[0]),
+            instance_type_args.add_unique(new_type, typeclass.args[0]),
             *typeclass.args[1:],
         )