事件

当代码对象执行时，会发生各种工具可能感兴趣的事件。通过激活事件和注册回调函数，工具可以以任何适合它们的方式响应这些事件。事件可以全局设置，也可以为单个代码对象设置。

对于 3.12，CPython 将支持以下事件

• PY_START：Python 函数的开始（在调用后立即发生，被调用者的帧将在堆栈上）
• PY_RESUME：Python 函数的恢复（对于生成器和协程函数），除了 throw() 调用。
• PY_THROW：Python 函数通过 throw() 调用恢复。
• PY_RETURN：Python 函数的返回（在返回前立即发生，被调用者的帧将在堆栈上）。
• PY_YIELD：Python 函数的 yield（在 yield 前立即发生，被调用者的帧将在堆栈上）。
• PY_UNWIND：在异常展开期间从 Python 函数退出。
• CALL：Python 代码中的调用（事件在调用之前发生）。
• C_RETURN：从任何可调用对象返回，除了 Python 函数（事件在返回后发生）。
• C_RAISE：从任何可调用对象引发异常，除了 Python 函数（事件在退出后发生）。
• RAISE：引发异常，除了那些导致 STOP_ITERATION 事件的异常。
• EXCEPTION_HANDLED：异常已处理。
• LINE：即将执行的指令的行号与前一条指令的行号不同。
• INSTRUCTION – VM 指令即将执行。
• JUMP – 控制流图中的无条件跳转。
• BRANCH – 条件分支被采用（或不被采用）。
• STOP_ITERATION – 引发人工的 StopIteration；请参阅 STOP_ITERATION 事件。

将来可能会添加更多事件。

所有事件都将是 sys.monitoring 中 events 命名空间的属性。所有事件都将由一个2的幂的整数表示，因此它们可以通过 | 运算符进行组合。

事件分为三组

工具标识符

虚拟机最多可以同时支持6个工具。在注册或激活事件之前，工具应选择一个标识符。标识符是0到5范围内的整数。

sys.monitoring.use_tool_id(id, name:str) -> None
sys.monitoring.free_tool_id(id) -> None
sys.monitoring.get_tool(id) ->  str | None

如果 id 正在使用中，sys.monitoring.use_tool_id 会引发 ValueError。如果 id 正在使用中，sys.monitoring.get_tool 返回工具的名称，否则返回 None。

所有ID在VM中对于事件的处理方式相同，但预定义了以下ID以方便工具协作

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

没有义务设置ID，也没有任何东西阻止工具使用即使已被占用的ID。但是，鼓励工具使用唯一的ID并尊重其他工具。

例如，如果调试器已附加且 DEBUGGER_ID 正在使用中，它应该报告错误，而不是不顾一切地继续执行。

OPTIMIZER_ID 为 Cinder 或 PyTorch 等希望优化 Python 代码但需要以依赖于更广泛上下文的方式决定优化内容的工具提供。

全局设置事件

事件可以通过修改被监控的事件集进行全局控制

• sys.monitoring.get_events(tool_id:int)->int 返回表示所有活动事件的 int。
• sys.monitoring.set_events(tool_id:int, event_set: int) 激活 event_set 中设置的所有事件。如果 tool_id 未在使用中，则引发 ValueError。

默认情况下没有活动事件。

每个代码对象事件

事件也可以按代码对象进行控制

• sys.monitoring.get_local_events(tool_id:int, code: CodeType)->int 返回 code 的所有本地事件
• sys.monitoring.set_local_events(tool_id:int, code: CodeType, event_set: int) 激活 event_set 中设置的 code 的所有本地事件。如果 tool_id 未在使用中，则引发 ValueError。

本地事件会添加到全局事件中，但不会屏蔽它们。换句话说，所有全局事件都会为代码对象触发，无论本地事件如何。

注册回调函数

要为事件注册可调用对象，请调用

sys.monitoring.register_callback(tool_id:int, event: int, func: Callable | None) -> Callable | None

如果已为给定的 tool_id 和 event 注册了另一个回调，则该回调将被注销并返回。否则，register_callback 返回 None。

可以通过调用 sys.monitoring.register_callback(tool_id, event, None) 来注销函数。

回调函数可以随时注册和注销。

注册或注销回调函数将生成一个 sys.audit 事件。

回调函数中的事件

对于注册了该回调的工具，回调函数及其被调用函数中的事件将暂停。

这意味着其他工具将在其他工具的回调函数中看到事件。这对于调试分析工具可能很有用，但会产生误导性分析结果，因为调试器工具将显示在分析中。

事件顺序

如果一条指令触发多个事件，它们将按以下顺序发生

• LINE
• INSTRUCTION
• 所有其他事件（每条指令只能发生其中一个事件）

每个事件都按照 ID 的升序传递给工具。

“call”事件组

大多数事件是独立的；设置或禁用一个事件对其他事件没有影响。然而，CALL、C_RAISE 和 C_RETURN 事件构成一个组。如果这些事件中的任何一个被设置或禁用，那么该组中的所有事件都将被设置或禁用。禁用 CALL 事件不会禁用匹配的 C_RAISE 或 C_RETURN，但会禁用所有后续事件。

sys.monitoring 命名空间的属性

• def use_tool_id(id)->None
• def free_tool_id(id)->None
• def get_events(tool_id: int)->int
• def set_events(tool_id: int, event_set: int)->None
• def get_local_events(tool_id: int, code: CodeType)->int
• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def restart_events()->None
• DISABLE: object
• MISSING: object

访问“仅调试”功能

标准库的一些功能对普通代码不可访问，但对调试器可访问。例如，设置局部变量或行号。

这些功能将对回调函数可用。

性能

如果没有活动事件，本 PEP 应该对性能产生小的积极影响。实验表明，不直接支持 sys.settrace() 可以带来 1% 到 2% 的加速。

sys.settrace() 的性能将大致相同。sys.setprofile() 的性能应该更好。然而，依赖于 sys.settrace() 和 sys.setprofile() 的工具可以通过使用本 PEP 提供的 API 变得更快。

如果只有少量事件处于活动状态，例如用于调试器，那么回调的开销将比 sys.settrace() 小几个数量级，并且比使用 PEP 523 便宜得多。

通过在所有回调中返回 DISABLE，可以以非常低的成本实现代码覆盖率工具。

对于高度插装的代码，例如使用 LINE，性能应该优于 sys.settrace，但不会好很多，因为性能将主要由回调中花费的时间决定。

对于优化虚拟机，例如未来版本的 CPython（以及 PyPy 如果他们选择支持此 API），在长时间运行的程序中更改活动事件集可能会非常昂贵，可能需要数百毫秒，因为它会触发去优化。一旦发生这种去优化，性能应该会恢复，因为虚拟机可以重新优化插装代码。

通常这些操作可以认为是快速的

• def get_events(tool_id: int)->int
• def get_local_events(tool_id: int, code: CodeType)->int
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def get_tool(tool_id) -> str | None

这些操作较慢，但并非特别慢

• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None

这些操作应被视为缓慢

• def use_tool_id(id, name:str)->None
• def free_tool_id(id)->None
• def set_events(tool_id: int, event_set: int)->None
• def restart_events()->None

慢操作的速度取决于它们发生的时间。如果它们在程序早期，在模块加载之前完成，它们应该相当便宜。

调试器

覆盖率工具

覆盖率工具需要跟踪控制图的哪些部分已执行。为此，它们需要注册 PY_ 事件以及 JUMP 和 BRANCH。

然后，这些信息可以在执行完成后转换回基于行的报告。

分析器

简单的分析器需要收集有关调用的信息。为此，分析器应注册以下事件

• PY_START
• PY_RESUME
• PY_THROW
• PY_RETURN
• PY_YIELD
• PY_UNWIND
• CALL
• C_RAISE
• C_RETURN