signal.alarm()在Windows上完全失效，因Windows无POSIX alarm()机制且未定义signal.SIGALRM；Linux/macOS下仅主线程可用，需注册handler、调用alarm(seconds)并清除，不支持浮点秒数，阻塞IO可中断而CPU计算可能延迟；跨平台推荐concurrent.futures.ThreadPoolExecutor。
为什么 signal.alarm() 在 Windows 上完全失效
因为 Windows 没有 POSIX 的 alarm() 信号机制，signal.SIGALRM 根本未定义。直接在 Windows 上运行基于 signal.alarm() 的超时装饰器会抛出 AttributeError: module 'signal' has no attribute 'SIGALRM'。这不是代码写错了，是系统级限制——别试了，换方案。
Linux/macOS 下用 signal 实现方法级超时的硬约束
必须在主线程中使用，且被装饰的方法不能是类的 __init__、__del__ 或任何被子线程调用的方法（signal 是进程级、仅主线程有效）。关键逻辑是：注册 signal.signal(signal.SIGALRM, handler)，在方法入口调用 signal.alarm(seconds)，正常返回前调用 signal.alarm(0) 清除定时器。
-
必须捕获
TimeoutError而非Exception：自定义 handler 应显式raise TimeoutError，避免吞掉其他异常 -
signal.alarm()不支持浮点秒数，最小单位是 1 秒；若需亚秒级（如 0.5s），得换threading.Timer+raise_exception等黑科技（不推荐） - 若方法内调用了阻塞 IO（如
requests.get()、time.sleep()），SIGALRM能中断它；但若方法正执行纯 CPU 计算（如大循环），信号可能被延迟投递，直到下一次 Python 字节码检查点
跨平台兼容的替代方案：用 concurrent.futures.ThreadPoolExecutor 包裹
这是目前最稳妥的通用解法：把方法调用扔进独立线程，主线程用 future.result(timeout=...) 控制等待时间。它天然绕过 signal 的平台限制，且能真正中断阻塞调用（通过线程终止，注意不是强制 kill）。
示例装饰器核心逻辑：
立即学习“Python免费学习笔记（深入）”；
def timeout(seconds):
def decorator(func):
def wrapper(*args, **kwargs):
with ThreadPoolExecutor(max_workers=1) as executor:
future = executor.submit(func, *args, **kwargs)
try:
return future.result(timeout=seconds)
except TimeoutError:
raise TimeoutError(f"{func.__name__} timed out after {seconds}s")
return wrapper
return decorator
- 每次调用都新建
ThreadPoolExecutor开销略大，高频场景建议复用实例 - 无法中断正在执行的 CPU 密集型任务（线程仍在跑，只是主线程放弃了等待），需配合方法内部定期检查
threading.current_thread().ident或共享 flag - 装饰器对
self参数透明，可直接用于实例方法
装饰器里传参和类方法绑定的常见坑
如果装饰器本身带参数（如 @timeout(3)），三层嵌套函数容易搞混作用域。最常踩的坑是：在 wrapper 中直接引用外层 func 没问题，但若想读取实例的属性（如 self.timeout_config），必须确保装饰器是作用在方法上，而非类或静态方法——否则 self 不存在。
- 不要在装饰器闭包里存
self引用：wrapper是在调用时才拿到self，闭包捕获的是定义时的变量 - 若需动态超时（比如根据
self.level决定秒数），别用函数装饰器，改用类装饰器或在方法体内手动调用executor.submit(...).result(timeout=...) -
@staticmethod和@classmethod与超时装饰器组合时，确保wrapper正确透传cls或无参调用，否则会报missing 1 required positional argument
