From 24781099b3cd2dc5e9a605b89eedd838a473cfbc Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Tue, 16 Apr 2024 09:55:17 +0200 Subject: [PATCH 1/2] gh-117518: Clarify PyTuple_GetItem() borrowed reference in the doc --- Doc/c-api/tuple.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index b3710560ebe7ac..1e76c10c69fddb 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. + Return a :term:`borrowed reference`. It is borrowed from the tuple *p*: + it remains valid as long as you hold a strong reference to *p*. + To get a :term:`strong reference`, use + :c:func:`Py_NewRef(PyTuple_GetItem(...)) ` + or :c:func:`PySequence_GetItem`. + .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) From 51f39c9b7e7fbc763c007d785ddaeebceff05a97 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 17 Apr 2024 14:38:28 +0200 Subject: [PATCH 2/2] Change phrasing --- Doc/c-api/tuple.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 1e76c10c69fddb..0d68a360f347f8 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -59,8 +59,8 @@ 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. - Return a :term:`borrowed reference`. It is borrowed from the tuple *p*: - it remains valid as long as you hold a strong reference to *p*. + 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(...)) ` or :c:func:`PySequence_GetItem`.