Argument for sys.settrace() callbacks documented incorrectly

[robertkern]

BPO	6798
Nosy	@birkenfeld, @terryjreedy

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2010-10-15.16:42:47.103>
created_at = <Date 2009-08-28.23:52:04.019>
labels = ['type-bug', 'docs']
title = 'Argument for sys.settrace() callbacks documented incorrectly'
updated_at = <Date 2010-10-15.16:42:47.102>
user = 'https://bugs.python.org/robertkern'

bugs.python.org fields:

activity = <Date 2010-10-15.16:42:47.102>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2010-10-15.16:42:47.103>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2009-08-28.23:52:04.019>
creator = 'robert.kern'
dependencies = []
files = []
hgrepos = []
issue_num = 6798
keywords = []
message_count = 5.0
messages = ['92050', '92125', '112700', '112745', '118799']
nosy_count = 4.0
nosy_names = ['georg.brandl', 'terry.reedy', 'eli.bendersky', 'robert.kern']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6798'
versions = ['Python 3.1', 'Python 2.7', 'Python 3.2']

[robertkern]

The final 'arg' argument of the sys.settrace() callback is documented to
be None for the 'c_return' and 'c_exception' events, but it appears to
be the function object itself. Additionally, the 'return' event's
argument may be None if the 'return' event is being generated because of
an exception. These errors also exist in the Py_tracefunc documentation
in the C API. The latter error is not particularly important for the
Python API, but in the C API the argument may be a NULL pointer.

I am happy to make the corrections if someone will confirm that my
analysis is correct.

[birkenfeld]

It certainly seems to be implemented this way in ceval.c. I don't know
if the docs describe the implementation intent better, but I'd say that
this is then such a minor issue that just documenting the actual
behavior is the best thing to do.

[terryjreedy]

Eli, any comment on this?

[elibendersky]

I can confirm Robert's findings.

1. The documentation of C_RETURN and C_EXCEPTION indeed says None while the function object is passed. This is seen in the implementation of the C_TRACE macro in Python/ceval.c

2. The arg of RETURN can be indeed NULL when caused by an exception. This is seen in the PyEval_EvalFrameEx function of Python/ceval.c right after the 'fast_yield' label.

3. The C/API documentation of Py_tracefunc shares the same errors with sys.settrace

As Georg said, the docs should be fixed to reflect the correct behavior.

[birkenfeld]

Should be fixed in r85540.