8000 Clarify some details regarding `sys.monitoring` by brettcannon · Pull Request #133981 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Clarify some details regarding sys.monitoring #133981

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

Merged
merged 11 commits into from
Jul 3, 2025
Merged

Clarify some details regarding sys.monitoring #133981

Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
0dcae29
Clarify some details regarding `sys.monitoring`
brettcannon May 13, 2025
37fde1b
Drop a lead-in sentence
brettcannon May 13, 2025
08735b2
Merge branch 'main' into clarify-sys.monitoring
brettcannon May 26, 2025
f346fc7
Fix type signatures for callback examples
brettcannon May 27, 2025
7360c23
Merge branch 'main' into clarify-sys.monitoring
brettcannon May 27, 2025
0d53375
Tweak type annotations
brettcannon May 28, 2025
326b31e
Try clarifying that event activation locally and globally
brettcannon Jun 17, 2025
93e25eb
Shift some things around
brettcannon Jun 17, 2025
236cd17
Merge branch 'main' into clarify-sys.monitoring
brettcannon Jun 17, 2025
4284e06
Clarify that `PY_UNWIND` includes directly raised exceptions
brettcannon Jun 17, 2025
75f9d6f
Tweak phrasing
brettcannon Jun 19, 2025
File filter

Filter by extension

Filter by extension
Conversations 8000
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 22 additions & 14 deletions Doc/library/sys.monitoring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ events, use the expression ``PY_RETURN | PY_START``.
if get_events(DEBUGGER_ID) == NO_EVENTS:
...

Events are divided into three groups:
Setting this event deactivates all events.

.. _monitoring-event-local:

Expand Down Expand Up @@ -292,9 +292,10 @@ in Python (see :ref:`c-api-monitoring`).
Activates all the local events 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,
regardless of the local events.
Local events add to global events. In other words, all global events
will trigger for a code object, regardless of the local events. Events
will also only trigger once regardless of whether the same event is
registered both globally and locally for a code object.


Disabling events
Expand Down Expand Up @@ -325,8 +326,6 @@ except for a few breakpoints.
Registering callback functions
------------------------------

To register a callable for events call

.. function:: register_callback(tool_id: int, event: int, func: Callable | None, /) -> Callable | None

Registers the callable *func* for the *event* with the given *tool_id*
Expand All @@ -353,37 +352,46 @@ Callback function arguments
that there are no arguments to the call.

When an active event occurs, the registered callback function is called.
Callback functions returning any object other than :data:`DISABLE` will have no effect.
Different events will provide the callback function with different arguments, as follows:

* :monitoring-event:`PY_START` and :monitoring-event:`PY_RESUME`::

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

* :monitoring-event:`PY_RETURN` and :monitoring-event:`PY_YIELD`::

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

* :monitoring-event:`CALL`, :monitoring-event:`C_RAISE` and :monitoring-event:`C_RETURN`::
* :monitoring-event:`CALL`, :monitoring-event:`C_RAISE` and :monitoring-event:`C_RETURN`
(*arg0* can be :data:`MISSING` specifically)::

func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any
func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object

*code* represents the code object where the call is being made, while
*callable* is the object that is about to be called (and thus
triggered the event).
If there are no arguments, *arg0* is set to :data:`sys.monitoring.MISSING`.

For instance methods, *callable* will be the function object as found on the
class with *arg0* set to the instance (i.e. the ``self`` argument to the
method).

* :monitoring-event:`RAISE`, :monitoring-event:`RERAISE`, :monitoring-event:`EXCEPTION_HANDLED`,
:monitoring-event:`PY_UNWIND`, :monitoring-event:`PY_THROW` and :monitoring-event:`STOP_ITERATION`::

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

* :monitoring-event:`LINE`::

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

* :monitoring-event:`BRANCH_LEFT`, :monitoring-event:`BRANCH_RIGHT` and :monitoring-event:`JUMP`::

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

Note that the *destination_offset* is where the code will next execute.

* :monitoring-event:`INSTRUCTION`::

func(code: CodeType, instruction_offset: int) -> DISABLE | Any
func(code: CodeType, instruction_offset: int) -> object
Loading
0