gh-156725: document O(N) behavior of PyCode_Addr2Line and the private line-table API by Himesh-rupchandani · Pull Request #156736 · python/cpython

Himesh-rupchandani · 2026-08-31T18:58:41Z

Summary

The C-API docs for PyCode_Addr2Line pointed to the PEP 626 section describing
PyLineTable_InitAddressRange, PyLineTable_NextAddressRange, and
PyLineTable_PreviousAddressRange. Those functions were renamed with a leading
underscore and moved to the private header Include/internal/pycore_code.h; they
are no longer a public C-API.

This docs PR:

notes that PyCode_Addr2Line is O(N) in the number of instructions;
points to the current private line-table iteration API (_PyCode_InitAddressRange,
_PyLineTable_NextAddressRange, _PyLineTable_PreviousAddressRange) and flags
them as internal/unstable.

I left the request to expose these as PyUnstable public APIs as a separate feature
proposal, per the issue.](gh-156725: Document O(N) behavior of PyCode_Addr2Line)

python-cla-bot · 2026-08-31T18:58:46Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-08-31T19:02:43Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #35357485 | 📁 Comparing 22c7ae9 against main (486b000)

🔍 Preview build

207 files changed · + 9 added · ± 198 modified

+ Added

± Modified

…rivate 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).

maurycy · 2026-09-02T13:29:48Z

+    .. 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.


I'm not sure if we should document internal. Users should not be calling them, and pointing it from the docs might send the wrong message.

https://docs.python.org/3/c-api/stable.html#:~:text=Names%20prefixed%20by%20an%20underscore

maurycy · 2026-09-02T13:32:29Z

-    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


Unstable has specific meaning:

https://docs.python.org/3/c-api/stable.html#unstable-c-api

ZeroIntensity · 2026-10-20T17:20:41Z

+    ``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::


I agree that we shouldn't document internal APIs. In a separate PR, let's instead promote these to the unstable API.

ZeroIntensity · 2026-10-20T17:22:47Z

+    instructions in the code object, so it is not suitable for iterating over
+    all the line numbers in a code object.


I wouldn't say that it's not suitable, it's just not performant:

Suggested change

instructions in the code object, so it is not suitable for iterating over

all the line numbers in a code object.

instructions in the code object, so it is not performant for iterating over

all the line numbers in a code object.

Himesh-rupchandani · 2026-10-21T06:59:48Z

Thanks for the review @ZeroIntensity and @maurycy! I have updated the wording to performant and removed the internal line-table API section as suggested. Also happy to open a separate PR promoting the address-range functions to the unstable C API if you'd like!

Himesh-rupchandani · 2026-10-21T07:07:11Z

Thanks for the review @ZeroIntensity and @maurycy! I have updated the wording to performant and removed the internal line-table API section as suggested.

ZeroIntensity · 2026-10-22T17:22:40Z

Per the issue, this API is outdated, and we shouldn't mention it in the docs.

ZeroIntensity · 2026-10-22T17:23:13Z


-    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


It may be O(N). It's not a guarantee.

Himesh-rupchandani · 2026-10-23T15:06:33Z

Thanks @ZeroIntensity! Updated This is -> This may be and removed the outdated PEP 626 reference.

ZeroIntensity

LGTM

miss-islington-app · 2026-10-23T17:43:52Z

Thanks @Himesh-rupchandani for the PR, and @ZeroIntensity for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

bedevere-app · 2026-10-23T17:44:08Z

GH-160453 is a backport of this pull request to the 3.15 branch.

bedevere-app · 2026-10-23T17:44:15Z

GH-160454 is a backport of this pull request to the 3.14 branch.

…6736) (GH-160454) (cherry picked from commit 8d11920) Co-authored-by: Himesh Rupchandani <rupchandanihimesh69@gmail.com>

…6736) (GH-160453) (cherry picked from commit 8d11920) Co-authored-by: Himesh Rupchandani <rupchandanihimesh69@gmail.com>

Himesh-rupchandani requested a review from ZeroIntensity as a code owner August 31, 2026 18:58

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Aug 31, 2026

github-project-automation Bot added this to Docs PRs Aug 31, 2026

github-project-automation Bot moved this to Todo in Docs PRs Aug 31, 2026

bedevere-app Bot mentioned this pull request Aug 31, 2026

PyCode_Addr2Line point to out of date PEP 626 #156725

Open

bedevere-app Bot added the awaiting review label Aug 31, 2026

Himesh-rupchandani force-pushed the gh-156725-code-addrtoline-docs branch from 3f8d96b to 7707506 Compare August 31, 2026 19:07

maurycy reviewed Sep 2, 2026

View reviewed changes

Merge branch 'main' into pythongh-156725-code-addrtoline-docs

17ae603

ZeroIntensity reviewed Oct 20, 2026

View reviewed changes

Update code.rst

7739eef

ZeroIntensity reviewed Oct 22, 2026

View reviewed changes

Update code.rst

22c7ae9

ZeroIntensity approved these changes Oct 23, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Oct 23, 2026

ZeroIntensity added needs backport to 3.14 bugs and security fixes needs backport to 3.15 bugs and security fixes labels Oct 23, 2026

ZeroIntensity merged commit 8d11920 into python:main Oct 23, 2026
38 checks passed

bedevere-app Bot removed the awaiting merge label Oct 23, 2026

github-project-automation Bot moved this from Todo to Done in Docs PRs Oct 23, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Oct 23, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Oct 23, 2026

ZeroIntensity pushed a commit that referenced this pull request Oct 23, 2026

[3.14] gh-156725: Document O(N) behavior of PyCode_Addr2Line (GH-15…

1f9c28d

…6736) (GH-160454) (cherry picked from commit 8d11920) Co-authored-by: Himesh Rupchandani <rupchandanihimesh69@gmail.com>

ZeroIntensity pushed a commit that referenced this pull request Oct 23, 2026

[3.15] gh-156725: Document O(N) behavior of PyCode_Addr2Line (GH-15…

2bc1255

…6736) (GH-160453) (cherry picked from commit 8d11920) Co-authored-by: Himesh Rupchandani <rupchandanihimesh69@gmail.com>

		instructions in the code object, so it is not suitable for iterating over
		all the line numbers in a code object.

Conversation

Himesh-rupchandani commented Aug 31, 2026 • edited by ZeroIntensity Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

python-cla-bot Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

maurycy Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

Himesh-rupchandani commented Oct 21, 2026

Uh oh!

Himesh-rupchandani commented Oct 21, 2026

Uh oh!

ZeroIntensity Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

Himesh-rupchandani commented Oct 23, 2026

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Oct 23, 2026

Uh oh!

bedevere-app Bot commented Oct 23, 2026

Uh oh!

bedevere-app Bot commented Oct 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Himesh-rupchandani commented Aug 31, 2026 •

edited by ZeroIntensity

Loading

python-cla-bot Bot commented Aug 31, 2026 •

edited

Loading

read-the-docs-community Bot commented Aug 31, 2026 •

edited

Loading