From: Peter Bierma <zintensitydev@gmail.com>
Date: Fri, 7 Nov 2025 18:46:47 +0000 (-0500)
Subject: gh-141004: Document `PyTraceBack*` APIs (GH-141192)
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=HEAD;p=thirdparty%2FPython%2Fcpython.git

gh-141004: Document `PyTraceBack*` APIs (GH-141192)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index b6f9399337e..f525ee7a046 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -1237,3 +1237,37 @@ Warning types
 
 .. versionadded:: 3.10
    :c:data:`PyExc_EncodingWarning`.
+
+
+Tracebacks
+==========
+
+.. c:var:: PyTypeObject PyTraceBack_Type
+
+   Type object for traceback objects. This is available as
+   :class:`types.TracebackType` in the Python layer.
+
+
+.. c:function:: int PyTraceBack_Check(PyObject *op)
+
+   Return true if *op* is a traceback object, false otherwise. This function
+   does not account for subtypes.
+
+
+.. c:function:: int PyTraceBack_Here(PyFrameObject *f)
+
+   Replace the :attr:`~BaseException.__traceback__` attribute on the current
+   exception with a new traceback prepending *f* to the existing chain.
+
+   Calling this function without an exception set is undefined behavior.
+
+   This function returns ``0`` on success, and returns ``-1`` with an
+   exception set on failure.
+
+
+.. c:function:: int PyTraceBack_Print(PyObject *tb, PyObject *f)
+
+   Write the traceback *tb* into the file *f*.
+
+   This function returns ``0`` on success, and returns ``-1`` with an
+   exception set on failure.