@@ -258,6 +258,17 @@ Dictionary Objects
258258 value represents offsets within the internal dictionary structure, and
259259 since the structure is sparse, the offsets are not consecutive.
260260
261+ .. note ::
262+
263+ On the free-threaded build, this function can be used safely inside a
264+ critical section. However, the references returned for *pkey * and *pvalue *
265+ are :term: `borrowed <borrowed reference> ` and are only valid while the
266+ critical section is held. If you need to use these objects outside the
267+ critical section or when the critical section can be suspended, create a
268+ :term: `strong reference <strong reference> ` (for example, using
269+ :c:func: `Py_NewRef `).
270+
271+
261272 For example::
262273
263274 PyObject *key, *value;
@@ -295,24 +306,13 @@ Dictionary Objects
295306 :c:macro: `Py_BEGIN_CRITICAL_SECTION ` to lock the dictionary while iterating
296307 over it::
297308
298- .. note ::
299-
300- On the :term: `free-threaded <free threading> ` build, this function can be
301- used safely inside a critical section. However, the references returned
302- for *pkey * and *pvalue * are :term: `borrowed <borrowed reference> ` and only
303- valid while the critical section is held. If you need to use these objects
304- outside the critical section or when the critical section can be suspended,
305- create :term: `strong reference <strong reference> ` (for example, with
306- :c:func: `Py_NewRef `).
307-
308- .. code-block:: c
309-
310309 Py_BEGIN_CRITICAL_SECTION(self->dict);
311310 while (PyDict_Next(self->dict, &pos, &key, &value)) {
312- ...
311+ ...
313312 }
314313 Py_END_CRITICAL_SECTION();
315314
315+
316316.. c :function :: int PyDict_Merge (PyObject *a, PyObject *b, int override)
317317
318318 Iterate over mapping object *b * adding key-value pairs to dictionary *a *.
0 commit comments