Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-02-13 19:04:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.13] Document that returning sys.monitoring.DISABLE in response to a global event raises ValueError (GH-140726) (GH-141015)

Browse source 
Document that returning `sys.monitoring.DISABLE` in response to a global event raises `ValueError` (GH-140726)
(cherry picked from commit 8a7dbb7a68)

Co-authored-by: Brett Cannon <brett@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2025-11-04 19:36:40 +01:00 • committed by GitHub
parent 56146059d3
commit aa4dd4ece8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 19 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

28
Doc/library/sys.monitoring.rst
View file

@ -198,14 +198,17 @@ by another event:
The :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events
are controlled by the :monitoring-event:`CALL` event.
:monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be seen if the
corresponding :monitoring-event:`CALL` event is being monitored.
:monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be
seen if the corresponding :monitoring-event:`CALL` event is being monitored.
.. _monitoring-event-global:
Other events
''''''''''''
Other events are not necessarily tied to a specific location in the
program and cannot be individually disabled.
program and cannot be individually disabled via :data:`DISABLE`.
The other events that can be monitored are:
@ -264,12 +267,13 @@ in Python (see :ref:`c-api-monitoring`).
.. function:: get_local_events(tool_id: int, code: CodeType, /) -> int
Returns all the local events for *code*
Returns all the :ref:`local events <monitoring-event-local>` for *code*
.. function:: set_local_events(tool_id: int, code: CodeType, event_set: int, /) -> None
Activates all the local events for *code* which are set in *event_set*.
Raises a :exc:`ValueError` if *tool_id* is not in use.
Activates all the :ref:`local events <monitoring-event-local>` for *code*
which are set in *event_set*. Raises a :exc:`ValueError` if *tool_id* is not
in use.
Local events add to global events, but do not mask them.
In other words, all global events will trigger for a code object,
@ -284,15 +288,21 @@ Disabling events
A special value that can be returned from a callback function to disable
events for the current code location.
Local events can be disabled for a specific code location by returning
:data:`sys.monitoring.DISABLE` from a callback function. This does not change
which events are set, or any other code locations for the same event.
:ref:`Local events <monitoring-event-local>` can be disabled for a specific code
location by returning :data:`sys.monitoring.DISABLE` from a callback function.
This does not change which events are set, or any other code locations for the
same event.
Disabling events for specific locations is very important for high
performance monitoring. For example, a program can be run under a
debugger with no overhead if the debugger disables all monitoring
except for a few breakpoints.
If :data:`DISABLE` is returned by a callback for a
:ref:`global event <monitoring-event-global>`, :exc:`ValueError` will be raised
by the interpreter in a non-specific location (that is, no traceback will be
provided).
.. function:: restart_events() -> None
Enable all the events that were disabled by :data:`sys.monitoring.DISABLE`