Local trace function return value: bug or documentation issue

[L3viathan]

Bug report

The documentation of sys.settrace claims:

The local trace function should return a reference to itself (or to another function for further tracing in that scope), or None to turn off tracing in that scope.

Returning None inside a local trace function should therefore disable tracing. However, it doesn't:

def global_tf(*_):
    return local_tf

def local_tf(f, e, _):
    print(e, f)
    return None

def some_function():
    1
    2

import sys
sys.settrace(global_tf)
some_function()

Running this code produces three events within some_function (one for each line and one return), even though every invocation of the local trace function returns None.

Your environment

• CPython versions tested on: 3.11, 3.10, 3.9 (behaviour differs slightly: just one line event)
• Operating system and architecture: macOS (3.11, 3.10, 3.9), Linux (3.11)

I see three possibilities:

• This is a misunderstanding, there's something I missed.
• This is a bug in the documentation. In that case, the docs should be changed to something like "The local trace function can return a reference to another function for further tracing in that scope, or None to continue tracing that scope." I could write the PR in that case.
• The behaviour is a bug. In that case, I think this part of the code should be changed to set frame.f_trace to None in the else case: https://github.com/python/cpython/blob/main/Python/sysmodule.c#L997-L1002 (thanks to @godlygeek for pointing out the place this is checked in). I could try writing the PR in that case.

Linked PRs

• gh-104232: Change sys.settrace docs to reflect actual behaviour #104245
• gh-104232: Fix sys.settrace docs to reflect the reality #110516
• [3.11] GH-104232: Fix statement about trace return values (GH-110516) #111045
• [3.12] GH-104232: Fix statement about trace return values (GH-110516) #111047

[L3viathan]

Looking further back in history, it has worked this way since at least Python 2.2. Assuming there is in fact a discrepancy between docs and code, it seems clear that we should only change documentation of the longstanding (>20 years) behaviour.

[thatbirdguythatuknownot]

Looking further back in history, it has worked this way since at least Python 2.2. Assuming there is in fact a discrepancy between docs and code, it seems clear that we should only change documentation of the longstanding (>20 years) behaviour.

@L3viathan the specific portion of code has done such since Python 2.2, but the behavior only changes in Python 3.10. What changed it?

[nedbat]

See #56201 and #78980.

[gaogaotiantian]

Do we have a test for this specific behavior, whether it was intended or not?

[L3viathan]

@gaogaotiantian Doesn't look like it. The local trace function in https://github.com/python/cpython/blob/main/Lib/test/test_sys_settrace.py always returns itself.