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中。如我所料，这行不通。我相信这是因为Pluggy实现的间接是动态的。必须运行代码，以便add_hookspecs()的{{1}}方法可以定义可用的挂钩。

我发现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钩子的类型注释定义为外部.pyi文件？
如果是，myhook()文件将包含什么以及在哪里存储，以便.pyi在运行类型检查时将其提取？
是否可以进行注释，以便钩子实现者和钩子调用者都获得有用的类型提示？

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)

Answer 2

Brad答案中的许多事情都可以在plugin.pyi文件中完成。我有以下内容（可能非常不完整）：plugy.pyi：

from types import ModuleType
from typing import Callable, Type, TypeVar, Generic, Any


F = TypeVar("F", bound=Callable[..., Any])


class HookspecMarker:
    def __init__(self, name: str) -> None:
        ...

    def __call__(self, func: F) -> F:
        ...


class HookimplMarker:
    def __init__(self, name: str) -> None:
        ...

    def __call__(self, func: F) -> F:
        ...


Spec = TypeVar("Spec")


class PluginManager(Generic[Spec]):
    def __init__(self, name: str) -> None:
        ...

    def load_setuptools_entrypoints(self, name: str) -> None:
        ...

    def add_hookspecs(self, module: Type[Spec]) -> None:
        ...

    def register(self, module: ModuleType) -> None:
        ...

    hook: Spec

这使我可以如下创建插件管理器：

import pluggy
from typing import TYPE_CHECKING
from .hookspecs import PluginSpec
from .plugins import localplugins


if TYPE_CHECKING:
    PluginManager = pluggy.PluginManager[PluginSpec]
else:
    PluginManager = pluggy.PluginManager

plugin: PluginManager = pluggy.PluginManager("mypackage")
plugin.add_hookspecs(PluginSpec)
plugin.load_setuptools_entrypoints("mypackage")
plugin.register(localplugins)

hookspec必须是静态类方法：

from typing import Any
import pluggy


hookspec = pluggy.HookspecMarker("mypackage")


class PluginSpec:
    @staticmethod
    @hookspec
    def plugin_func(*args: Any) -> None:
        ...

我该如何注释一个钩子规范的类型？

2 个答案: