本文详解如何为 signal.signal() 的 handler 参数添加准确的类型提示，包括必需的导入、参数类型定义及常见错误规避，帮助你在使用信号处理时获得完整的类型安全支持。
本文详解如何为 signal.signal() 的 handler 参数添加准确的类型提示，包括必需的导入、参数类型定义及常见错误规避，帮助你在使用信号处理时获得完整的类型安全支持。
在 Python 中，signal.signal(signum, handler) 的 handler 参数需满足特定签名：它必须是一个接受两个参数（signum: int 和 frame: FrameType | None）且返回 None 的可调用对象。若在类方法中作为处理器使用，还需正确标注 self 类型以支持类型检查器（如 mypy 或 PyCharm）推导。
✅ 正确类型提示写法
from types import FrameType
import signal
from typing import Self # Python 3.11+；3.10 及更早版本可用 from typing_extensions import Self
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 不提供栈帧）? 关键要点说明
-
signum: int：信号编号始终为整数（如signal.SIGINT值为 2），不可标注为signal.Signals枚举（因 C 层实际传入的是int，且signal.signal()签名明确要求int）； -
frame: FrameType | None：FrameType来自types模块，表示 Python 栈帧对象；None是合法值（如某些信号不附带执行上下文）； -
Self类型：用于标注实例方法中的self，确保类型检查器理解self.handler是绑定方法且类型稳定（避免误判为Callable[..., None]而丢失self上下文）； -
导入不可省略：
FrameType必须显式从types导入，Self在 Python ≥3.11 原生支持，旧版本需安装typing_extensions并导入。
⚠️ 常见错误与规避
- ❌ 错误：
def handler(self, signum, frame):—— 缺少所有类型注解，导致类型检查失效； - ❌ 错误：
frame: FrameType（无| None）—— 忽略None可能性，触发 mypy 报错Argument 2 to "signal" has incompatible type "Callable[[Any, int, FrameType], None]"； - ❌ 错误：
from signal import signal后未导入FrameType——FrameType不在signal模块中，会引发NameError或类型未解析。
✅ 额外建议：函数式处理器的类型提示
若使用独立函数而非方法，推荐使用 typing.Callable 显式声明：
from types import FrameType
import signal
from typing import Callable
def signal_handler(signum: int, frame: FrameType | None) -> None:
print("Caught signal")
# 类型安全调用
signal.signal(signal.SIGTERM, signal_handler) # ✅ mypy 可校验通过以上方式，你不仅能消除 IDE 警告，还能在重构或协作中获得更强的静态保障——信号处理器不再是“魔法回调”，而是类型清晰、可验证的一等公民。
