Matplotlib mpl_connect绑定MouseEvent类型注解时PyCharm告警问题求助

问题背景 #

为基于Tkinter的Matplotlib画布事件处理代码添加类型注解时，PyCharm抛出类型检查告警：

Expected type '(Event) -> Any' got '(event: MouseEvent) -> None' instead

具体场景：

• EventHandler类的on_press方法参数注解为MouseEvent
• mpl_connect方法期望接收参数类型为Event的回调函数
• MouseEvent是Event的子类，代码实际运行正常，但修改参数注解为Event后，使用MouseEvent独有属性时会触发新的类型告警
• 修改返回类型为Any无效，添加# noinspection PyTypeChecker可消除告警，但想了解告警原因及正确注解方式

告警原因 #

PyCharm的类型检查遵循函数类型逆变原则：

• 如果一个函数类型要求接收父类Event作为参数，那么传入一个仅接受子类MouseEvent作为参数的函数，在理论上是不安全的——类型检查器无法确定mpl_connect是否会传递非MouseEvent的Event实例给回调。
• 虽然实际中button_press_event只会传递MouseEvent，但类型检查器无法感知Matplotlib的这一事件绑定规则，因此抛出告警。

正确的类型注解方式 #

方式一：添加类型守卫（推荐） #

保持参数注解为Event，在方法内部通过isinstance检查事件类型，既满足mpl_connect的类型要求，又能安全访问MouseEvent的独有属性：

from matplotlib.backend_bases import Event, MouseEvent

class EventHandler:
    def on_press(self, event: Event) -> None:
        if isinstance(event, MouseEvent):
            # 此处可安全使用MouseEvent独有属性（如xdata、ydata）
            print(f"点击坐标：{event.xdata}, {event.ydata}")
        # 可选：处理非MouseEvent的情况

方式二：使用类型断言强制转换 #

如果确定事件只会是MouseEvent，可以用typing.cast告诉类型检查器回调函数符合要求：

from typing import Callable, cast
from matplotlib.backend_bases import Event, MouseEvent
import matplotlib.pyplot as plt

class EventHandler:
    def on_press(self, event: MouseEvent) -> None:
        print(f"点击坐标：{event.xdata}, {event.ydata}")

fig, ax = plt.subplots()
handler = EventHandler()
# 强制转换回调类型，消除告警
fig.canvas.mpl_connect(
    'button_press_event',
    cast(Callable[[Event], None], handler.on_press)
)

内容的提问来源于stack exchange，提问作者Gareth Friend