https://github.com/python/cpython/commit/aa4dd4ece8d3344710aad74a27840d98d9894526 commit: aa4dd4ece8d3344710aad74a27840d98d9894526 branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: brettcannon <[email protected]> date: 2025-11-04T18:36:40Z summary:
[3.13] Document that returning `sys.monitoring.DISABLE` in response to a global event raises `ValueError` (GH-140726) (GH-141015) Document that returning `sys.monitoring.DISABLE` in response to a global event raises `ValueError` (GH-140726) (cherry picked from commit 8a7dbb7a68b5da1f3f1805f564c028f1eea4ebc3) Co-authored-by: Brett Cannon <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/sys.monitoring.rst diff --git a/Doc/library/sys.monitoring.rst b/Doc/library/sys.monitoring.rst index 8fdddbb7bfea81..f8b0350ad3cbc6 100644 --- a/Doc/library/sys.monitoring.rst +++ b/Doc/library/sys.monitoring.rst @@ -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` _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
