[3.12] gh-117518: Clarify PyTuple_GetItem() borrowed reference in the doc (GH-117920...

gh-117518: Clarify PyTuple_GetItem() borrowed reference in the doc (GH-117920)
(cherry picked from commit 4605a197bd84da1a232bd835d8e8e654f2fef220)

Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 9bc3dab0c9c12cfb12f221461c3bf5a7f5334ed2..e0186c1f5229c14282da3abe42f27bea5f2198ad 100644 (file)
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -59,6 +59,12 @@ Tuple Objects
    Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
    negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
 
+   The returned reference is borrowed from the tuple *p*
+   (that is: it is only valid as long as you hold a reference to *p*).
+   To get a :term:`strong reference`, use
+   :c:func:`Py_NewRef(PyTuple_GetItem(...)) <Py_NewRef>`
+   or :c:func:`PySequence_GetItem`.
+
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)