From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 27 Aug 2025 13:58:07 +0000 (+0200)
Subject: [3.14] gh-138098: Clarify strong references in `PyDict_Next` docs on the free-threade... 
X-Git-Tag: v3.14.0rc3~126
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=65bf6f549b7ff0a120a88e57b6831e3279f6b3ca;p=thirdparty%2FPython%2Fcpython.git

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

Co-authored-by: PrinceNaroliya <naroliyaprince@gmail.com>
---

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)