sys.monitoring – Мониторинг событий выполнения¶sys.monitoring – Execution event monitoring

Регистрация и использование инструментов¶Registering and using tools

sys.monitoring.use_tool_id(tool_id: int, name: str, /) → None¶

Должен быть вызван до того, как tool_id можно будет использовать. tool_id должен находиться в диапазоне от 0 до 5 включительно. Вызывает исключение ValueError, если tool_id уже используется.

sys.monitoring.clear_tool_id(tool_id: int, /) → None¶

Отменяет регистрацию всех событий и функций обратного вызова, связанных с tool_id.

sys.monitoring.free_tool_id(tool_id: int, /) → None¶

Должен быть вызван, когда инструмент больше не требует tool_id. Перед освобождением tool_id будет вызвана функция clear_tool_id().

sys.monitoring.get_tool(tool_id: int, /) → str | None¶

Возвращает имя инструмента, если tool_id используется, в противном случае возвращает None. tool_id должен находиться в диапазоне от 0 до 5 включительно.

Все идентификаторы обрабатываются виртуальной машиной одинаково с точки зрения событий, но следующие идентификаторы предопределены для упрощения совместной работы инструментов:

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

Локальные события¶Local events

Локальные события связаны с нормальным выполнением программы и происходят в чётко определённых местах. Все локальные события можно отключать для каждого места отдельно. Локальные события:

• PY_START

• PY_RESUME

• PY_RETURN

• PY_YIELD

• CALL

• LINE

• INSTRUCTION

• JUMP

• BRANCH_LEFT

• BRANCH_RIGHT

• STOP_ITERATION

Устаревшее событие¶Deprecated event

• BRANCH

Событие BRANCH устарело в версии 3.14. Использование событий BRANCH_LEFT и BRANCH_RIGHT даёт гораздо лучшую производительность, так как их можно отключать независимо.

Вспомогательные события¶Ancillary events

Вспомогательные события можно отслеживать, как и другие, но они управляются другим событием:

• C_RAISE

• C_RETURN

События C_RETURN и C_RAISE управляются событием CALL. События C_RETURN и C_RAISE будут видны только при отслеживании соответствующего события CALL.

Прочие события¶Other events

Другие события не обязательно привязаны к конкретному месту в программе и не могут быть отключены индивидуально для каждого места.

Прочие события, которые можно отслеживать:

• PY_THROW

• PY_UNWIND

• RAISE

• EXCEPTION_HANDLED

• RERAISE

Событие STOP_ITERATION¶The STOP_ITERATION event

PEP 380 указывает, что при возврате значения из генератора или корутины возбуждается исключение StopIteration. Однако это очень неэффективный способ возврата значения, поэтому некоторые реализации Python, в частности CPython 3.12+, не возбуждают исключение, если оно не будет видно другому коду.

Чтобы инструменты могли отслеживать реальные исключения без замедления генераторов и корутин, предусмотрено событие STOP_ITERATION. STOP_ITERATION может быть локально отключено.

Обратите внимание, что событие STOP_ITERATION и событие RAISE для исключения StopIteration эквивалентны и при генерации событий считаются взаимозаменяемыми. Реализации будут отдавать предпочтение STOP_ITERATION по соображениям производительности, но могут генерировать событие RAISE с StopIteration.

Глобальная настройка событий¶Setting events globally

События можно контролировать глобально, изменяя набор отслеживаемых событий.

sys.monitoring.get_events(tool_id: int, /) → int¶

Возвращает int, представляющую все активные события.

sys.monitoring.set_events(tool_id: int, event_set: int, /) → None¶

Активирует все события, установленные в event_set. Возбуждает ValueError, если tool_id не используется.

По умолчанию ни одно событие не активно.

События для каждого объекта кода¶Per code object events

События также можно контролировать для каждого объекта кода. Функции, определённые ниже и принимающие types.CodeType, должны быть готовы принять объект-имитацию от функций, не определённых на Python (см. Monitoring C API).

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, /) → None¶

Активирует все локальные события для code, установленные в event_set. Возбуждает ValueError, если tool_id не используется.

Отключение событий¶Disabling events

sys.monitoring.DISABLE¶

Специальное значение, которое можно вернуть из функции обратного вызова, чтобы отключить события для текущего местоположения в коде.

Локальные события можно отключить для конкретного места в коде, вернув sys.monitoring.DISABLE из функции обратного вызова. Это не меняет, какие события установлены, и не затрагивает другие места в коде для того же события.

Другие события можно отключить для каждого объекта кода отдельно, возвращая sys.monitoring.DISABLE из функции колбэка. Это отключает событие для всего объекта кода (для текущего инструмента).

Отключение событий для конкретных местоположений очень важно для высокопроизводительного мониторинга. Например, программа может выполняться под отладчиком без накладных расходов, если отладчик отключает весь мониторинг, кроме нескольких точек останова.

sys.monitoring.restart_events() → None¶

Включить все события, которые были отключены вызовом sys.monitoring.DISABLE для всех инструментов.

Аргументы функции обратного вызова¶Callback function arguments

sys.monitoring.MISSING¶

Специальное значение, которое передаётся функции обратного вызова, чтобы указать, что у вызова нет аргументов.

Когда происходит активное событие, вызывается зарегистрированная функция обратного вызова. Функции обратного вызова, возвращающие объект, отличный от DISABLE, не будут иметь эффекта. Разные события передают функции обратного вызова разные аргументы, как показано ниже:

• PY_START и PY_RESUME:

  func(code: CodeType, instruction_offset: int) -> object
  

• PY_RETURN и PY_YIELD:

  func(code: CodeType, instruction_offset: int, retval: object) -> object
  

• CALL, C_RAISE и C_RETURN (arg0 может быть именно MISSING):

  func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object
  

  code представляет объект кода, в котором производится вызов, а callable – объект, который будет вызван (и тем самым вызвал событие). Если аргументов нет, arg0 устанавливается в sys.monitoring.MISSING.

  Для методов экземпляра callable будет объектом функции, найденным в классе, а arg0 устанавливается в экземпляр (т.е. аргумент self метода).

• RAISE, RERAISE, EXCEPTION_HANDLED, PY_UNWIND, PY_THROW и STOP_ITERATION:

  func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
  

• LINE:

  func(code: CodeType, line_number: int) -> object
  

• BRANCH_LEFT, BRANCH_RIGHT и JUMP:

  func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
  

  Обратите внимание, что destination_offset – это место, где код будет выполняться далее.

• INSTRUCTION:

  func(code: CodeType, instruction_offset: int) -> object