[3.14] gh-141004: Document `PyErr_ProgramTextObject` and `PyErr_ProgramText` (GH...

gh-141004: Document `PyErr_ProgramTextObject` and `PyErr_ProgramText` (GH-141250)
(cherry picked from commit be1c72a45d54cdd35e0a830e18224c4c74be808c)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
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 f525ee7a0461fe91117a131a6fa26fa9491b95e7..c58aa659e1b1b4608a17251429a23761b4a5ce0c 100644 (file)
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -331,6 +331,23 @@ For convenience, some of these functions will always return a
    use.
 
 
+.. c:function:: PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)
+
+   Get the source line in *filename* at line *lineno*. *filename* should be a
+   Python :class:`str` object.
+
+   On success, this function returns a Python string object with the found line.
+   On failure, this function returns ``NULL`` without an exception set.
+
+
+.. c:function:: PyObject *PyErr_ProgramText(const char *filename, int lineno)
+
+   Similar to :c:func:`PyErr_ProgramTextObject`, but *filename* is a
+   :c:expr:`const char *`, which is decoded with the
+   :term:`filesystem encoding and error handler`, instead of a
+   Python object reference.
+
+
 Issuing warnings
 ================