PEP 669 tweaks proposal

Core Development
1

PEP 669 (Low Impact Monitoring for CPython) is is the PR review state.

As a reviewer I tried to write a simple tracing function using the new API, and I found a few small things that I’d like to change in the PEP. Since the PEP has been approved by the SC already such changes need some formal discussion and SC approval, but I think it’s pretty simple, since these are just UI tweaks that @markshannon has already said wouldn’t be much work to implement.

Unless there’s serious discussion about these tweaks I plan to propose the PEP changes to the SC so we can have closure on this (and land the PR).

Change to the Tool ID registration API

Most calls to the monitoring API require an ‘ID’ so the implementation can separately track the needs of a debugger, a profiler, and other tools. As a matter of “politeness” it is recommended that tools register their tool identifier with the API. This is currently voluntary. Based on my experience trying out the new API, I feel that it would be a slightly nicer user experience if tool ID registration was mandatory. API calls like set_events would require that the tool ID is registered. My proposal is to change the registration function use_tool_id(id: int, name: str) -> None to use_tool_id(name: str) -> int, and to make other APIs that take a tool ID as an argument raise an exception if the tool ID is not registered. The predefined tool IDs for debugger, coverage, profiler and optimizer can be treated similar to the stdin/stdout/stderr file descriptors in UNIX. (PR Discussion.)

Changing the order in which events are delivered

Currently, when both LINE and INSTRUCTION events happen for the same instruction, the PEP specifies that the INSTRUCTION event is triggered before the LINE event. I’ve found this slightly confusing and surprising, and propose that the LINE event be delivered first. That way a tracing tool can always rely on the LINE event to tell it the line number of the subsequent instructions. This feels more natural and less surprising than generating the INSTRUCTION event before the LINE event. My proposal is to reverse these (so LINE is delivered first), leaving everything else the same. (PR discussion.)

5 Likes
2

Both of those make sense to me.

1 Like
3

Change to the Tool ID registration API

Checking that the ID has been registered when calling set_events is reasonable, but I don’t want to change the API of use_tool_id.

The API was discussed in the main thread, and there was consensus that having predefined ids made for a nicer API. Having a debugger and a coverage tool at the same time should be fine. Having two debuggers is not a good idea.

Changing the order in which events are delivered

That way a tracing tool can always rely on the LINE event to tell it the line number of the subsequent instructions.

Individual instructions do not have meaningful line numbers. We attach line numbers to instructions to ensure that we implement PEP 626, but the bytecode compiler is free to rearrange things as long as the visible state of the VM is consistent with PEP 626.

I’m happy to make this change, though. It is easy to make, and makes the order of line and instruction events consistent with sys.settrace(). Just be aware that the line number attached to an individual instruction doesn’t really mean anything.

4

For the record I’m fine with keeping the signature of use_tool_id().