Feature or enhancement

Proposal:

I would like to propose making the PY_UNWIND monitoring event available as a local event. The rationale for doing this is that some tools can be interested in trapping per-function exit events. Currently, this is only possible with the PY_RETURN event when a function returns with a value. However, if a function is exited with an exception, there is no way of capturing that event on just that function. Making the PY_UNWIND event would allow monitoring tools to catch all function exit events.

import random, sys

m, e = sys.monitoring, sys.monitoring.events

m.use_tool_id(0, "debugger")

def monitor(event):
    def _(f):
        m.register_callback(0, event, f)
    return _

@monitor(e.PY_START)
def _(*_, **__):
    print("entering", sys._getframe(1))

@monitor(e.PY_UNWIND)
def _(*_, **__):
    print("exiting ", sys._getframe(1), "with exception")

def foo():
    raise RuntimeError()

def bar():
    return foo()

def baz():
    return bar()

m.set_local_events(0, random.choice([foo, bar, baz]).__code__, e.PY_UNWIND | e.PY_START)

try:
    baz()
except Exception:
    pass

# entering <frame at 0x101602f80, file 'test_py_unwind_local.py', line 34, code baz>
# exiting  <frame at 0x101602f80, file 'test_py_unwind_local.py', line 35, code baz> with exception

A debugger is an example of a tool that can benefit from PY_UNWIND being a local event.

The proposed change will break the current assumption that local events always require bytecode instrumentation. Instead, the PY_UNWIND event will simply make a local tool check instead of a global one inside monitor_unwind. No changes to bytecode or any other parts are required.

This is an extension of the current implementation of PEP 669 whereby PY_UNWIND will be available as a local event. The behaviour of the already existing global event will not be touched. As such, the proposed change will be guaranteed to be backwards-compatible.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/pep-669-low-impact-monitoring-for-cpython/13018/82

Linked PRs

• gh-142186: make PY_UNWIND available as a local event #142179
• gh-142186: all-local PEP-669 events #146182
• gh-142186: Revert the unintended value change in the PY_MONITORING_EVENT_* values from gh-146182 #148955