From: PrinceNaroliya <naroliyaprince@gmail.com>
Date: Mon, 25 Aug 2025 14:53:26 +0000 (+0530)
Subject: gh-138098: Clarify strong references in `PyDict_Next` docs on the free-threaded build... 
X-Git-Tag: v3.15.0a1~593
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9ee0214b5dd982ac9fbe18dcce0e8787456e29af;p=thirdparty%2FPython%2Fcpython.git

gh-138098: Clarify strong references in `PyDict_Next` docs on the free-threaded build (GH-138106)
---

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index e55c5c80cb83..0fbe26b56c0a 100644
--- 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)