From: Savannah Ostrowski <savannahostrowski@gmail.com>
Date: Mon, 27 May 2024 12:20:28 +0000 (-0700)
Subject: GH-117283: Add doc warning for `PyTuple_SetItem` refcount > 1 (#117916)
X-Git-Tag: v3.14.0a1~1755
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=041a566f3f987619cef7d6ae7915ba93e39d2d1e;p=thirdparty%2FPython%2Fcpython.git

GH-117283: Add doc warning for `PyTuple_SetItem` refcount > 1 (#117916)
---

diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 0d68a360f347..52668d16b744 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -105,6 +105,12 @@ Tuple Objects
       is being replaced; any reference in the tuple at position *pos* will be
       leaked.
 
+   .. warning::
+
+      This macro should *only* be used on tuples that are newly created.
+      Using this macro on a tuple that is already in use (or in other words, has
+      a refcount > 1) could lead to undefined behavior.
+
 
 .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)