[3.14] gh-138098: Clarify strong references in PyDict_Next docs on the free-threaded build (GH-138106) (#138141)

miss-islington · PrinceNaroliya · web-flow · commit 65bf6f549b7f · 2025-08-27T16:58:07.000+03:00
Co-authored-by: PrinceNaroliya &lt;naroliyaprince@gmail.com&gt;
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
@@ -301,6 +301,15 @@ Dictionary Objects
       }
       Py_END_CRITICAL_SECTION();
 
+   .. note::
+
+      On the free-threaded build, this function can be used safely inside a
+      critical section. However, the references returned for *pkey* and *pvalue*
+      are :term:`borrowed <borrowed reference>` and are only valid while the
+      critical section is held. If you need to use these objects outside the
+      critical section or when the critical section can be suspended, create a
+      :term:`strong reference <strong reference>` (for example, using
+      :c:func:`Py_NewRef`).
 
 .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
 
