如何为插件钩子规范注释类型？

Question

我想在我的插件钩子规范中添加类型注释，以便可以对钩子实现进行类型检查。使用pluggy documentation中的这个简化示例：

import pluggy  # type: ignore

hookspec = pluggy.HookspecMarker("myproject")
hookimpl = pluggy.HookimplMarker("myproject")


class MySpec(object):
    """A hook specification namespace."""

    @hookspec
    def myhook(self, arg1, arg2):
        """My special little hook that you can customize."""


class Plugin_1(object):
    """A hook implementation namespace."""

    @hookimpl
    def myhook(self, arg1, arg2):
        print("inside Plugin_1.myhook()")
        return arg1 + arg2 + "a" # intentional error


# create a manager and add the spec
pm = pluggy.PluginManager("myproject")
pm.add_hookspecs(MySpec)
# register plugins
pm.register(Plugin_1())
# call our `myhook` hook
# intentional incompatible type for parameter arg2
results = pm.hook.myhook(arg1=1, arg2="1")
print(results)

我相信正确有效的注释将是：

def myhook(self, arg1: int, arg2: int) -> int: ...

我尝试将此注释添加到hookspec。正如我所料，这不起作用。我相信这是因为插件实现的间接是动态的。必须运行代码，以便add_hookspecs()的PluginManager方法可以定义可用的钩子。

我看到pm.hook是pluggy.hooks._HookRelay类型，而pm.hook.myhook是pluggy.hooks._HookCaller的一个例子，它有__call__()方法。

我尝试使用stubgen为插件制作一组.pyi文件，然后以两种不同的方式将注释添加到pluggy.hooks._HookCaller：

class _HookCaller:
    def __init__(self, trace: Any) -> None: ...
    def myhook(self, arg1: int, arg2: int) -> int: ...
    def __call__(self, arg1: int, arg2: int) -> int: ...

当我执行MYPYPATH=./stubs mypy --verboes example.py时，我可以看到hooks.pyi被解析但是没有检测到参数类型不匹配。即使我从# type: ignore中删除import pluggy注释，此行为也是一致的。

问题：

1. 作为外部.pyi文件，是否可以定义myhook()钩子的类型注释？
2. 如果是这样，.pyi文件包含什么以及我在哪里存储它以便mypy在运行类型检查时选择它？
3. 是否可以注释钩子实现者和钩子调用者获得有用的类型提示？

Answer 1

第一个问题是@hookspec删除了myhook方法的类型提示：

from typing import TypeVar, Callable, Any, cast

# Improvement suggested by @oremanj on python/typing gitter
F = TypeVar("F", bound=Callable[..., Any])
hookspec = cast(Callable[[F], F], pluggy.HookspecMarker("myproject"))

该解决方法否定了对外部.pyi文件的要求。只需使用现有的钩子规范来定义类型提示。这解决了Q1和Q2：你不需要.pyi文件。只需使用typing.cast()给mypy一个提示，它无法从静态分析中学到：

# Add cast so that mypy knows that pm.hook
# is actually a MySpec instance. Without this
# hint there really is no way for mypy to know
# this.
pm.hook = cast(MySpec, pm.hook)

可以通过添加注释来检查：

# Uncomment these when running through mypy to see
# how mypy regards the type
reveal_type(pm.hook)
reveal_type(pm.hook.myhook)
reveal_type(MySpec.myhook)

通过mypy运行：

plug.py:24: error: Unsupported operand types for + ("int" and "str")
plug.py:42: error: Revealed type is 'plug.MySpec'
plug.py:43: error: Revealed type is 'def (arg1: builtins.int, arg2: builtins.int) -> builtins.int'
plug.py:44: error: Revealed type is 'def (self: plug.MySpec, arg1: builtins.int, arg2: builtins.int) -> builtins.int'
plug.py:47: error: Argument "arg2" to "myhook" of "MySpec" has incompatible type "str"; expected "int"

现在mypy捕获了钩子调用者和钩子实现的类型问题（Q3）！

完整代码：

import pluggy  # type: ignore
from typing import TypeVar, Callable, Any, cast

# Improvement suggested by @oremanj on python/typing gitter
F = TypeVar("F", bound=Callable[..., Any])
hookspec = cast(Callable[[F], F], pluggy.HookspecMarker("myproject"))
hookimpl = pluggy.HookimplMarker("myproject")


class MySpec(object):
    """A hook specification namespace."""

    @hookspec
    def myhook(self, arg1: int, arg2: int) -> int:
        """My special little hook that you can customize."""


class Plugin_1(object):
    """A hook implementation namespace."""

    @hookimpl
    def myhook(self, arg1: int, arg2: int) -> int:
        print("inside Plugin_1.myhook()")
        return arg1 + arg2 + 'a'


# create a manager and add the spec
pm = pluggy.PluginManager("myproject")
pm.add_hookspecs(MySpec)

# register plugins
pm.register(Plugin_1())

# Add cast so that mypy knows that pm.hook
# is actually a MySpec instance. Without this
# hint there really is no way for mypy to know
# this.
pm.hook = cast(MySpec, pm.hook)

# Uncomment these when running through mypy to see
# how mypy regards the type
# reveal_type(pm.hook)
# reveal_type(pm.hook.myhook)
# reveal_type(MySpec.myhook)

# this will now be caught by mypy
results = pm.hook.myhook(arg1=1, arg2="1")
print(results)