gh-117518: Clarify PyTuple_GetItem() borrowed reference in the doc (GH-117920)

vstinner · web-flow · commit 4605a197bd84 · 2024-04-19T10:41:37.000+02:00
diff --git 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)
 
