From: Victor Stinner <vstinner@python.org>
Date: Fri, 19 Apr 2024 08:41:37 +0000 (+0200)
Subject: gh-117518: Clarify PyTuple_GetItem() borrowed reference in the doc (GH-117920)
X-Git-Tag: v3.13.0b1~341
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4605a197bd84da1a232bd835d8e8e654f2fef220;p=thirdparty%2FPython%2Fcpython.git

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

diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index b3710560ebe7..0d68a360f347 100644
--- 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)