Skip to content

Document that returning sys.monitoring.DISABLE in response to a global event raises ValueError #140726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document that returning sys.monitoring.DISABLE in response to a global event raises ValueError #140726

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6c7b4f1
Document that returning `sys.monitoring.DISABLE` in response to a glo…
brettcannon Oct 28, 2025
8a05aa5
Update Doc/library/sys.monitoring.rst
brettcannon Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions Doc/library/sys.monitoring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,14 +216,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:

Expand Down Expand Up @@ -289,12 +292,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.


Disabling events
Expand All @@ -305,15 +309,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`
Expand Down
Loading