From: Mark Shannon <mark@hotpy.org>
Date: Fri, 2 Apr 2021 12:24:57 +0000 (+0100)
Subject: Document PyCode_Addr2Line function. (GH-25111)
X-Git-Tag: v3.10.0a7~23
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=58384c6ab01bbc35cc14cdeb716f6c45a3df426b;p=thirdparty%2FPython%2Fcpython.git

Document PyCode_Addr2Line function. (GH-25111)

* Document PyCode_Addr2Line function.

* Clarify when to use PEP 626 line iterators.
---

diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index b3a17f1898e8..6e18a4225e8f 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -51,3 +51,11 @@ bound into a function.
    Return a new empty code object with the specified filename,
    function name, and first line number.  It is illegal to
    :func:`exec` or :func:`eval` the resulting code object.
+
+.. 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.
+    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 `the API described in PEP 626
+    <https://www.python.org/dev/peps/pep-0626/#out-of-process-debuggers-and-profilers>`_.