Closes #136 (#189)

* Closes #136

* Fixes github actions

* Fixes CI

* Fixes CI

* Fixes CI

Author: sobolevn

.github/workflows/test.yml

@@ -1,6 +1,11 @@
 name: test
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   build:

classes/_typeclass.py

@@ -92,6 +92,16 @@ def typeclass(
     then it will be called,
     otherwise the default implementation will be called instead.
 
+    You can also use ``.instance`` with just annotation for better readability:
+
+    .. code:: python
+
+        >>> @example.instance
+        ... def _example_float(instance: float) -> str:
+        ...     return 0.5
+
+        >>> assert example(5.1) == 0.5
+
     .. rubric:: Generics
 
     We also support generic, but the support is limited.
@@ -395,6 +405,13 @@ def instance(
     ]:
         """Case for regular typeclasses."""
 
+    @overload
+    def instance(
+        self,
+        type_argument: Callable[[_InstanceType], _ReturnType],
+    ) -> NoReturn:
+        """Case for typeclasses that are defined by annotation only."""
+
     @overload
     def instance(
         self,
@@ -423,10 +440,27 @@ def instance(
         would not match ``Type[_InstanceType]`` type due to ``mypy`` rules.
 
         """
-        isinstance(object(), type_argument)  # That's how we check for generics
+        original_handler = None
+        if not is_protocol:
+            # If it is not a protocol, we can try to get an annotation from
+            annotations = getattr(type_argument, '__annotations__', None)
+            if annotations:
+                original_handler = type_argument
+                type_argument = annotations[
+                    type_argument.__code__.co_varnames[0]  # noqa: WPS609
+                ]
+
+        # That's how we check for generics,
+        # generics that look like `List[int]` or `set[T]` will fail this check,
+        # because they are `_GenericAlias` instance,
+        # which raises an exception for `__isinstancecheck__`
+        isinstance(object(), type_argument)
 
         def decorator(implementation):
             container = self._protocols if is_protocol else self._instances
             container[type_argument] = implementation
             return implementation
+
+        if original_handler is not None:
+            return decorator(original_handler)  # type: ignore
         return decorator

classes/contrib/mypy/classes_plugin.py

@@ -19,6 +19,7 @@
 
 from typing import Callable, Optional, Type, Union
 
+from mypy.nodes import ARG_POS, Decorator, MemberExpr
 from mypy.plugin import FunctionContext, MethodContext, MethodSigContext, Plugin
 from mypy.typeops import bind_self
 from mypy.types import AnyType, CallableType, Instance
@@ -46,15 +47,16 @@ class _AdjustArguments(object):
     """
 
     def __call__(self, ctx: FunctionContext) -> MypyType:
+        defn = ctx.arg_types[0][0]
         is_defined_by_class = (
-            isinstance(ctx.arg_types[0][0], CallableType) and
-            not ctx.arg_types[0][0].arg_types and
-            isinstance(ctx.arg_types[0][0].ret_type, Instance)
+            isinstance(defn, CallableType) and
+            not defn.arg_types and
+            isinstance(defn.ret_type, Instance)
         )
 
         if is_defined_by_class:
             return self._adjust_protocol_arguments(ctx)
-        elif isinstance(ctx.arg_types[0][0], CallableType):
+        elif isinstance(defn, CallableType):
             return self._adjust_function_arguments(ctx)
         return ctx.default_return_type
 
@@ -144,12 +146,87 @@ class _AdjustInstanceSignature(object):
     """
 
     def __call__(self, ctx: MethodContext) -> MypyType:
+        if not isinstance(ctx.type, Instance):
+            return ctx.default_return_type
+        if not isinstance(ctx.default_return_type, CallableType):
+            return ctx.default_return_type
+
         instance_type = self._adjust_typeclass_callable(ctx)
         self._adjust_typeclass_type(ctx, instance_type)
         if isinstance(instance_type, Instance):
             self._add_supports_metadata(ctx, instance_type)
         return ctx.default_return_type
 
+    @classmethod
+    def from_function_decorator(cls, ctx: FunctionContext) -> MypyType:
+        """
+        It is used when ``.instance`` is used without params as a decorator.
+
+        Like:
+
+        .. code:: python
+
+           @some.instance
+           def _some_str(instance: str) -> str:
+               ...
+
+        """
+        is_decorator = (
+            isinstance(ctx.context, Decorator) and
+            len(ctx.context.decorators) == 1 and
+            isinstance(ctx.context.decorators[0], MemberExpr) and
+            ctx.context.decorators[0].name == 'instance'
+        )
+        if not is_decorator:
+            return ctx.default_return_type
+
+        passed_function = ctx.arg_types[0][0]
+        assert isinstance(passed_function, CallableType)
+
+        if not passed_function.arg_types:
+            return ctx.default_return_type
+
+        annotation_type = passed_function.arg_types[0]
+        if isinstance(annotation_type, Instance):
+            if annotation_type.type and annotation_type.type.is_protocol:
+                ctx.api.fail(
+                    'Protocols must be passed with `is_protocol=True`',
+                    ctx.context,
+                )
+                return ctx.default_return_type
+        else:
+            ctx.api.fail(
+                'Only simple instance types are allowed, got: {0}'.format(
+                    annotation_type,
+                ),
+                ctx.context,
+            )
+            return ctx.default_return_type
+
+        ret_type = CallableType(
+            arg_types=[passed_function],
+            arg_kinds=[ARG_POS],
+            arg_names=[None],
+            ret_type=AnyType(TypeOfAny.implementation_artifact),
+            fallback=passed_function.fallback,
+        )
+        instance_type = ctx.api.expr_checker.accept(  # type: ignore
+            ctx.context.decorators[0].expr,  # type: ignore
+        )
+
+        # We need to change the `ctx` type from `Function` to `Method`:
+        return cls()(MethodContext(
+            type=instance_type,
+            arg_types=ctx.arg_types,
+            arg_kinds=ctx.arg_kinds,
+            arg_names=ctx.arg_names,
+            args=ctx.args,
+            callee_arg_names=ctx.callee_arg_names,
+            default_return_type=ret_type,
+            context=ctx.context,
+            api=ctx.api,
+        ))
+
     def _adjust_typeclass_callable(
         self,
         ctx: MethodContext,
@@ -302,6 +379,9 @@ def get_function_hook(
         """Here we adjust the typeclass constructor."""
         if fullname == 'classes._typeclass.typeclass':
             return _AdjustArguments()
+        if fullname == 'instance of _TypeClass':
+            # `@some.instance` call without params:
+            return _AdjustInstanceSignature.from_function_decorator
         return None
 
     def get_method_hook(
@@ -310,6 +390,7 @@ def get_method_hook(
     ) -> Optional[Callable[[MethodContext], MypyType]]:
         """Here we adjust the typeclass with new allowed types."""
         if fullname == 'classes._typeclass._TypeClass.instance':
+            # `@some.instance` call with explicit params:
             return _AdjustInstanceSignature()
         return None
 

docs/pages/concept.rst

@@ -13,6 +13,9 @@ works differently for ``"string"`` and ``[1, 2]``.
 Or ``+`` operator that works for numbers like "add"
 and for strings it works like "concatenate".
 
+Existing approaches
+-------------------
+
 Classes and interfaces
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -45,8 +48,17 @@ to add your own types to this process.
 So, how does it work?
 
 
+Typeclasses
+-----------
+
+So, typeclasses help us to build new abstractions near the existing types,
+not inside them.
+
+Basically, we will learn how to dispatch
+different logic based on predefined set of types.
+
 Steps
------
+~~~~~
 
 To use typeclasses you should understand these steps:
 
@@ -75,7 +87,7 @@ Let's define some instances:
 
 .. code:: python
 
-  >>> @json.instance(str)
+  >>> @json.instance  # You can use just the annotation
   ... def _json_str(instance: str) -> str:
   ...     return '"{0}"'.format(instance)
 
@@ -87,6 +99,17 @@ Let's define some instances:
 That's how we define instances for our typeclass.
 These instances will be executed when the corresponding type will be supplied.
 
+.. note::
+  ``.instance`` can use explicit type or just an existing annotation.
+  It is recommended to use the explicit type, because annotations can be tricky.
+  For example, sometimes you have to use ``ForwardRef``
+  or so called string-based-annotations. It is not supported.
+  Complex type from annotations are also not supported
+  like: ``Union[str, int]``.
+
+  So, use annotations for the simplest cases only
+  and use explicit types in all other cases.
+
 And the last step is to call our typeclass
 with different value of different types: