Document PyCode_Addr2Line function. #25111
Conversation
Doc/c-api/code.rst
Outdated
| .. c:function:: int PyCode_Addr2Line(PyCodeObject *co, int byte_offset) | ||
|
|
||
| Return the line number of the of instruction that occurs on or before ``byte_offset`` and ends after it. | ||
| This function is kept for backwards compatibility, its use is not recommended. |
There was a problem hiding this comment.
If this function should not be used, I suggest to officially deprecate it. Add ".. deprecated:: 3.10", add it to https://docs.python.org/dev/whatsnew/3.10.html#id3 and add Py_DEPRECATED() in the header file where it's defined. Usually, we wait at two Python releases before removing a function (PEP 387).
I checked Tools/gdb/libpython.py: it reimplements this function :-)
def addr2line(self, addrq):
'''
Get the line number for a given bytecode offset
Analogous to PyCode_Addr2Line; translated from pseudocode in
Objects/lnotab_notes.txt
'''
Doc/c-api/code.rst
Outdated
| For determining line numbers in a code object, use the API described in PEP 626: | ||
| https://www.python.org/dev/peps/pep-0626/#out-of-process-debuggers-and-profilers |
There was a problem hiding this comment.
| For determining line numbers in a code object, use the API described in PEP 626: | |
| https://www.python.org/dev/peps/pep-0626/#out-of-process-debuggers-and-profilers | |
| For determining line numbers in a code object, use `the API described in the PEP 626 | |
| <https://www.python.org/dev/peps/pep-0626/#out-of-process-debuggers-and-profilers>`_. |
markshannon
force-pushed
the
doc-api-func
branch
from
557dc94 to
5481eef
Compare
|
@vstinner Since the functions in PEP 626 aren't technically part of the API. We probably don't want to deprecate this. |
| If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead. | ||
|
|
||
| For effciently determining line numbers in a code object, use `the API described in PEP 626 | ||
| <https://www.python.org/dev/peps/pep-0626/#out-of-process-debuggers-and-profilers>`_. |
There was a problem hiding this comment.
I don't understand. PyLineTable_InitAddressRange() doesn't seem to be implemented in Python 3.10. Do you plan to implement it?
If it's not implemented yet, I suggest to remove this paragraph, and add it once it will be implemented.
There was a problem hiding this comment.
It is implemented https://github.com/python/cpython/blob/master/Objects/codeobject.c#L1259
It isn't part of the API, though. Which is why we need to keep PyCode_Addr2Line
Doc/c-api/code.rst
Outdated
|
|
||
| .. c:function:: int PyCode_Addr2Line(PyCodeObject *co, int byte_offset) | ||
|
|
||
| Return the line number of the of instruction that occurs on or before ``byte_offset`` and ends after it. |
There was a problem hiding this comment.
| Return the line number of the of instruction that occurs on or before ``byte_offset`` and ends after it. | |
| Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it. |
Doc/c-api/code.rst
Outdated
| Return the line number of the of instruction that occurs on or before ``byte_offset`` and ends after it. | ||
| If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead. | ||
|
|
||
| For effciently determining line numbers in a code object, use `the API described in PEP 626 |
There was a problem hiding this comment.
| For effciently determining line numbers in a code object, use `the API described in PEP 626 | |
| For effeciently determining line numbers in a code object, use `the API described in PEP 626 |
No description provided.