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 0d68a360f347f850e58a568d7c5b729adbc4d515..52668d16b74436866123cf0e961fa06c62e59c92 100644 (file)
--- 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)