本文详解如何为 signal.signal() 的 handler 参数添加准确、符合标准库类型的类型提示，包括必需的导入（FrameType、Self）、参数签名规范及常见误区。
本文详解如何为 `signal.signal()` 的 handler 参数添加准确、符合标准库类型的类型提示，包括必需的导入（`frametype`、`self`）、参数签名规范及常见误区。
在 Python 中为 signal.signal() 注册的信号处理器（handler）添加类型提示时，需严格遵循 signal 模块的运行时签名和类型定义。官方文档与 typeshed（Python 类型存根库）明确指出：handler 必须是形如 (int, FrameType | None) -> None 的可调用对象。当 handler 是实例方法时，还需正确标注 self 参数的类型。
以下是一个完整、可直接运行的示例：
from types import FrameType
import signal
from typing import Self # Python 3.11+；若使用 3.10 或更早版本，请改用 from typing import TYPE_CHECKING / from __future__ import annotations
class SomeClass:
def __init__(self: Self) -> None:
signal.signal(signal.SIGINT, self.handler)
def handler(self: Self, signum: int, frame: FrameType | None) -> None:
print(f"Received signal {signum}")
# 注意：frame 可能为 None（例如 SIGKILL 不触发帧捕获）
if frame is not None:
print(f"Stack frame at line {frame.f_lineno}")✅ 关键要点说明：
-
signum类型为int—— 这是 POSIX 信号编号（如SIGINT=2），非枚举或字符串； -
frame类型为FrameType | None—— 因为某些信号（如SIGKILL、SIGSTOP）不传递执行上下文，frame为None；必须显式允许None，否则类型检查器（如 mypy）会报错； - 使用
Self标注self参数（推荐于 Python 3.11+），确保方法返回类型与类实例一致，避免循环引用问题；若兼容旧版 Python，可用字符串字面量"SomeClass"替代Self，但Self更安全、更语义清晰； -
from types import FrameType是必需导入 ——FrameType并不在signal或typing模块中直接导出，遗漏将导致类型检查失败。
⚠️ 注意事项：
立即学习“Python免费学习笔记（深入）”；
- 不要使用
Callable[[int, Optional[FrameType]], None]手动构造类型 —— 这虽语法合法，但丢失了self上下文，无法正确描述绑定方法； - 避免将
frame: FrameType写为非可选类型（即不加| None），这不符合 CPython 实际行为，会在SIGALRM等无栈信号场景下引发类型误报； - 若 handler 需在类外复用（如静态方法或独立函数），签名应简化为
(signum: int, frame: FrameType | None) -> None，且无需self参数。
正确配置类型提示不仅能提升代码可维护性，还能让 IDE 提供精准补全与错误预警，是构建健壮信号处理逻辑的重要基础。
