sys.monitoring
--- 执行事件监测¶
Added in version 3.12.
备注
sys.monitoring
是 sys
模块内部的一个命名空间,而不是一个独立模块,因此不需要 import sys.monitoring
,只要简单地 import sys
然后使用 sys.monitoring
。
这个命名空间提供了对于激活和控制事件监控所需的函数和常量的访问。
在程序执行过程中,会发生对于监控执行的工具来说值得关注的事件。 sys.monitoring
命名空间提供了在相应事件发生时接收回调的操作方式。
monitoring API由三个部分组成:
工具标识符¶
工具标识符是一个整数及其所关联的名称。 工具标识符被用来防止工具之间的相互干扰并允许同时操作多个工作。 目前工具是完全独立的且不能被用于相互监控。 这一限制在将来可能会被取消。
在注册或激活事件之前,工具应选择一个标识符。 标识符是 0 到 5 的开区间内的整数。
注册和使用工具¶
- sys.monitoring.use_tool_id(tool_id: int, name: str, /) None ¶
必须在 tool_id 可被使用之前调用。 tool_id 必须在 0 到 5 的开区间内。 如果 tool_id 已被使用则会引发
ValueError
。
- sys.monitoring.clear_tool_id(tool_id: int, /) None ¶
Unregister all events and callback functions associated with tool_id.
- sys.monitoring.free_tool_id(tool_id: int, /) None ¶
Should be called once a tool no longer requires tool_id. Will call
clear_tool_id()
before releasing tool_id.
- sys.monitoring.get_tool(tool_id: int, /) str | None ¶
如果 tool_id 已被使用则返回工具名称,否则返回
None
。 tool_id 取值必须在 0 至 5 的开区间内。
虚拟机在处理事件时对所有 ID 都一视同仁,但为便于工具之间的协作而预定义了下列 ID:
sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5
事件¶
以下事件是受支持的:
- sys.monitoring.events.BRANCH¶
条件分支被采用(或不采用)。
- sys.monitoring.events.CALL¶
Python 代码中的调用(事件发生在调用之前)。
- sys.monitoring.events.C_RAISE¶
从任意可调用对象引发的异常。 Python 函数除外(事件发生在退出之后)。
- sys.monitoring.events.C_RETURN¶
从任意可调用对象返回,Python 函数除外(事件在返回之后发生)。
- sys.monitoring.events.EXCEPTION_HANDLED¶
一个异常被处理。
- sys.monitoring.events.INSTRUCTION¶
一个 VM 指令即将被执行。
- sys.monitoring.events.JUMP¶
在控制流图中进行一次无条件的跳转。
- sys.monitoring.events.LINE¶
一条与之前指令行号不同的指令即将被执行。
- sys.monitoring.events.PY_RESUME¶
恢复执行一个 Python 函数(用于生成器和协程函数),
throw()
调用除外。
- sys.monitoring.events.PY_RETURN¶
从一个 Python 函数返回(在返回之前立即发生,被调用方的帧将在栈中)。
- sys.monitoring.events.PY_START¶
开始一个 Python 函数(在调用之后立即发生,被调用方的帧将在栈中)
- sys.monitoring.events.PY_THROW¶
一个 Python 函数由
throw()
调用恢复执行。
- sys.monitoring.events.PY_UNWIND¶
在异常解除期间从一个 Python函数退出。
- sys.monitoring.events.PY_YIELD¶
从一个 Python 函数产出数据(在产出之前立即发生,被调用方的帧将在栈中)。
- sys.monitoring.events.RAISE¶
一个异常被引发,导致
STOP_ITERATION
事件的异常除外。
- sys.monitoring.events.STOP_ITERATION¶
一个
StopIteration
被人工引发;参见 the STOP_ITERATION event。
将来可能会添加更多事件。
这些事件都是 sys.monitoring.events
命名空间的属性。 每个事件用整数常量的 2 次幂来表示。 要定义一组事件,只需对多个单独事件执行按位或运算即可。 例如,要同时指定 PY_RETURN
和 PY_START
事件,则使用表达式 PY_RETURN | PY_START
。
- sys.monitoring.events.NO_EVENTS¶
代表
0
的别名以便用户可以这样执行显式比较:if get_events(DEBUGGER_ID) == NO_EVENTS: ...
事件被分为三组:
本地事件¶
本地事件与程序的正常执行相关联并且发生在明确定义的位置上。 所有本地事件都可以被禁用。 本地事件包括:
辅助事件¶
辅助事件可以像其他事件一样被监视,但是由另一个事件来控制:
C_RETURN
和 C_RAISE
事件是由 CALL
事件控制的。 C_RETURN
和 C_RAISE
事件只会在相应的 CALL
事件被监控时才能被看到。
其他事件¶
其他事件不一定与程序中的特定位置相关联并且不能被单独禁用。
可以被监视的其他事件包括:
STOP_ITERATION 事件¶
PEP 380 规定了当从生成器或协程返回值时可引发 StopIteration
异常。 不过,这是一种非常低效的返回值的方式,因此某些 Python 实现,比如 CPython 3.12+,只有在异常对其他代码可见时才会引发它。
为允许工具监视真正的异常而不会拖慢生成器和协程的运行,解释器提供了 STOP_ITERATION
事件。 STOP_ITERATION
可以被局部禁用,这与 RAISE
不同。
Note that the STOP_ITERATION
event and the RAISE
event for a StopIteration
exception are equivalent, and are treated as interchangeable
when generating events. Implementations will favor STOP_ITERATION
for
performance reasons, but may generate a RAISE
event with a StopIteration
.
开启和关闭事件¶
要监视一个事件,它必须被开启并注册相应的回调函数。 可以通过将事件设置为全局的或针对特定代码对象的来开启或关闭事件。
全局设置事件¶
通过修改被监视的事件集可以对事件进行全局控制。
- sys.monitoring.set_events(tool_id: int, event_set: int, /) None ¶
激活在 event_set 中设置的所有事件。 如果 tool_id 未被使用则会引发
ValueError
。
在默认情况下没有被激活的事件。
针对特定代码对象的事件¶
事件也可以基于每个代码对象来控制。 下面定义的接受一个 types.CodeType
的函数应当准备好接受来自不是在 Python 中定义的类似对象 (参见 监控 C API)。
- sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int, /) None ¶
激活在 event_set 中设置的针对 code 的所有局部事件。 如果 tool_id 未被使用则会引发
ValueError
。
局部事件将添加到全局事件中,但不会屏蔽全局事件。 换句话说,所有全局事件都会为代码对象触发,无论是否有局部事件。
禁用事件¶
- sys.monitoring.DISABLE¶
一个可从回调函数返回以禁用当前代码位置上的事件的特殊值。
可从回调函数返回 sys.monitoring.DISABLE
以禁用特定代码位置上的局部事件。 这不会改变已设置的事件,也不会改变同一事件的任何其他代码位置。
禁用特定位置的事件对高性能的监控非常重要。 例如,如果调试器禁用了除几个断点外的所有监控那么程序在调试器下运行时就不会产生额外的开销。
- sys.monitoring.restart_events() None ¶
启用
sys.monitoring.DISABLE
针对所有工具禁用的所有事件。
注册回调函数¶
要为事件注册一个可调用对象则要调用
- sys.monitoring.register_callback(tool_id: int, event: int, func: Callable | None, /) Callable | None ¶
使用给定的 tool_id 为 event 注册可调用对象 func
如果已经为给定的 tool_id 和 event 注册了另一个回调,它将被注销并返回。 在其他情况下
register_callback()
将返回None
。
函数可以通过调用 sys.monitoring.register_callback(tool_id, event, None)
来注销。
回调函数可在任何时候被注册或注销。
注册或注销回调函数将生成一个 sys.audit()
事件。
回调函数参数¶
- sys.monitoring.MISSING¶
一个传给回调函数表明该调用不附带任何参数的特殊值。
当一个激活的事件发生时,已注册的回调函数将被调用。 不同的事件将为回调函数提供不同的参数,如下所示:
-
func(code: CodeType, instruction_offset: int) -> DISABLE | Any
-
func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any
-
func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any
如果没有任何参数,则 arg0 将被设为
sys.monitoring.MISSING
。 RAISE
,RERAISE
,EXCEPTION_HANDLED
,PY_UNWIND
,PY_THROW
和STOP_ITERATION
:func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any
LINE
:func(code: CodeType, line_number: int) -> DISABLE | Any
-
func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any
请注意 destination_offset 是代码下一次执行的位置。 对于未进入的分支这将为该分支之后的指令的偏移量。
-
func(code: CodeType, instruction_offset: int) -> DISABLE | Any