From 770750634656195ca48d7efd8e6c99ee0581f9a3 Mon Sep 17 00:00:00 2001 From: Himesh Rupchandani Date: Tue, 1 Sep 2026 00:25:16 +0530 Subject: [PATCH] gh-156725: document O(N) behavior of PyCode_Addr2Line and the private line-table API The C-API docs for PyCode_Addr2Line pointed to the PEP 626 section that describes PyLineTable_InitAddressRange / PyLineTable_NextAddressRange / PyLineTable_PreviousAddressRange, but those functions have since been renamed with a leading underscore and moved to the private header Include/internal/pycore_code.h. Point to the current private names, note that they are not a stable public API, and document that PyCode_Addr2Line is O(N). --- Doc/c-api/code.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst index 57b77f92a7d2e6a..c244505217625ec 100644 --- a/Doc/c-api/code.rst +++ b/Doc/c-api/code.rst @@ -94,11 +94,27 @@ bound into a function. .. c:function:: int PyCode_Addr2Line(PyCodeObject *co, int byte_offset) - Return the line number of the 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. This is ``O(N)`` in the number of + instructions in the code object, so it is not suitable for iterating over + all the line numbers in a code object. + If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead. - For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626 - <0626#out-of-process-debuggers-and-profilers>`. + To iterate efficiently over the line numbers in a code object, use the + private, unstable line-table iteration APIs declared in the private header + ``Include/internal/pycore_code.h``: + + * ``_PyCode_InitAddressRange`` initializes a ``PyCodeAddressRange`` for a code object. + * ``_PyLineTable_NextAddressRange`` advances the range to the next + line-number entry. + * ``_PyLineTable_PreviousAddressRange`` retreats the range to the + previous entry. + + .. warning:: + These functions are **internal and not a public C-API**. They are + declared in a private header, may change or be removed without notice, + and are not exported as stable symbols. .. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)