Debian Codegraph @

Doc/c-api/dict.rst

raw
1 .. highlight:: c
2
3 .. _dictobjects:
4
5 Dictionary Objects
6 ------------------
7
8 .. index:: pair: object; dictionary
9
10
11 .. c:type:: PyDictObject
12
13 This subtype of :c:type:`PyObject` represents a Python dictionary object.
14
15
16 .. c:var:: PyTypeObject PyDict_Type
17
18 This instance of :c:type:`PyTypeObject` represents the Python dictionary
19 type. This is the same object as :class:`dict` in the Python layer.
20
21
22 .. c:function:: int PyDict_Check(PyObject *p)
23
24 Return true if *p* is a dict object or an instance of a subtype of the dict
25 type. This function always succeeds.
26
27
28 .. c:function:: int PyDict_CheckExact(PyObject *p)
29
30 Return true if *p* is a dict object, but not an instance of a subtype of
31 the dict type. This function always succeeds.
32
33
34 .. c:function:: PyObject* PyDict_New()
35
36 Return a new empty dictionary, or ``NULL`` on failure.
37
38
39 .. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
40
41 Return a :class:`types.MappingProxyType` object for a mapping which
42 enforces read-only behavior. This is normally used to create a view to
43 prevent modification of the dictionary for non-dynamic class types.
44
45
46 .. c:var:: PyTypeObject PyDictProxy_Type
47
48 The type object for mapping proxy objects created by
49 :c:func:`PyDictProxy_New` and for the read-only ``__dict__`` attribute
50 of many built-in types. A :c:type:`PyDictProxy_Type` instance provides a
51 dynamic, read-only view of an underlying dictionary: changes to the
52 underlying dictionary are reflected in the proxy, but the proxy itself
53 does not support mutation operations. This corresponds to
54 :class:`types.MappingProxyType` in Python.
55
56
57 .. c:function:: void PyDict_Clear(PyObject *p)
58
59 Empty an existing dictionary of all key-value pairs.
60
61
62 .. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
63
64 Determine if dictionary *p* contains *key*. If an item in *p* matches
65 *key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
66 This is equivalent to the Python expression ``key in p``.
67
68 .. note::
69
70 The operation is atomic on :term:`free threading <free-threaded build>`
71 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
72
73
74 .. c:function:: int PyDict_ContainsString(PyObject *p, const char *key)
75
76 This is the same as :c:func:`PyDict_Contains`, but *key* is specified as a
77 :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
78 :c:expr:`PyObject*`.
79
80 .. versionadded:: 3.13
81
82
83 .. c:function:: PyObject* PyDict_Copy(PyObject *p)
84
85 Return a new dictionary that contains the same key-value pairs as *p*.
86
87
88 .. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
89
90 Insert *val* into the dictionary *p* with a key of *key*. *key* must be
91 :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
92 ``0`` on success or ``-1`` on failure. This function *does not* steal a
93 reference to *val*.
94
95 .. note::
96
97 The operation is atomic on :term:`free threading <free-threaded build>`
98 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
99
100
101 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
102
103 This is the same as :c:func:`PyDict_SetItem`, but *key* is
104 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
105 rather than a :c:expr:`PyObject*`.
106
107
108 .. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
109
110 Remove the entry in dictionary *p* with key *key*. *key* must be :term:`hashable`;
111 if it isn't, :exc:`TypeError` is raised.
112 If *key* is not in the dictionary, :exc:`KeyError` is raised.
113 Return ``0`` on success or ``-1`` on failure.
114
115 .. note::
116
117 The operation is atomic on :term:`free threading <free-threaded build>`
118 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
119
120
121 .. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
122
123 This is the same as :c:func:`PyDict_DelItem`, but *key* is
124 specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
125 rather than a :c:expr:`PyObject*`.
126
127
128 .. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
129
130 Return a new :term:`strong reference` to the object from dictionary *p*
131 which has a key *key*:
132
133 * If the key is present, set *\*result* to a new :term:`strong reference`
134 to the value and return ``1``.
135 * If the key is missing, set *\*result* to ``NULL`` and return ``0``.
136 * On error, raise an exception, set *\*result* to ``NULL`` and return ``-1``.
137
138 .. note::
139
140 The operation is atomic on :term:`free threading <free-threaded build>`
141 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
142
143 .. versionadded:: 3.13
144
145 See also the :c:func:`PyObject_GetItem` function.
146
147
148 .. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
149
150 Return a :term:`borrowed reference` to the object from dictionary *p* which
151 has a key *key*. Return ``NULL`` if the key *key* is missing *without*
152 setting an exception.
153
154 .. note::
155
156 Exceptions that occur while this calls :meth:`~object.__hash__` and
157 :meth:`~object.__eq__` methods are silently ignored.
158 Prefer the :c:func:`PyDict_GetItemWithError` function instead.
159
160 .. note::
161
162 In the :term:`free-threaded build`, the returned
163 :term:`borrowed reference` may become invalid if another thread modifies
164 the dictionary concurrently. Prefer :c:func:`PyDict_GetItemRef`, which
165 returns a :term:`strong reference`.
166
167 .. versionchanged:: 3.10
168 Calling this API without an :term:`attached thread state` had been allowed for historical
169 reason. It is no longer allowed.
170
171
172 .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
173
174 Variant of :c:func:`PyDict_GetItem` that does not suppress
175 exceptions. Return ``NULL`` **with** an exception set if an exception
176 occurred. Return ``NULL`` **without** an exception set if the key
177 wasn't present.
178
179 .. note::
180
181 In the :term:`free-threaded build`, the returned
182 :term:`borrowed reference` may become invalid if another thread modifies
183 the dictionary concurrently. Prefer :c:func:`PyDict_GetItemRef`, which
184 returns a :term:`strong reference`.
185
186
187 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
188
189 This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
190 :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
191 :c:expr:`PyObject*`.
192
193 .. note::
194
195 Exceptions that occur while this calls :meth:`~object.__hash__` and
196 :meth:`~object.__eq__` methods or while creating the temporary :class:`str`
197 object are silently ignored.
198 Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
199 :c:func:`PyUnicode_FromString` *key* instead.
200
201 .. note::
202
203 In the :term:`free-threaded build`, the returned
204 :term:`borrowed reference` may become invalid if another thread modifies
205 the dictionary concurrently. Prefer :c:func:`PyDict_GetItemStringRef`,
206 which returns a :term:`strong reference`.
207
208
209 .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
210
211 Similar to :c:func:`PyDict_GetItemRef`, but *key* is specified as a
212 :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
213 :c:expr:`PyObject*`.
214
215 .. versionadded:: 3.13
216
217
218 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
219
220 This is the same as the Python-level :meth:`dict.setdefault`. If present, it
221 returns the value corresponding to *key* from the dictionary *p*. If the key
222 is not in the dict, it is inserted with value *defaultobj* and *defaultobj*
223 is returned. This function evaluates the hash function of *key* only once,
224 instead of evaluating it independently for the lookup and the insertion.
225
226 .. versionadded:: 3.4
227
228 .. note::
229
230 In the :term:`free-threaded build`, the returned
231 :term:`borrowed reference` may become invalid if another thread modifies
232 the dictionary concurrently. Prefer :c:func:`PyDict_SetDefaultRef`,
233 which returns a :term:`strong reference`.
234
235
236
237 .. c:function:: int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)
238
239 Inserts *default_value* into the dictionary *p* with a key of *key* if the
240 key is not already present in the dictionary. If *result* is not ``NULL``,
241 then *\*result* is set to a :term:`strong reference` to either
242 *default_value*, if the key was not present, or the existing value, if *key*
243 was already present in the dictionary.
244 Returns ``1`` if the key was present and *default_value* was not inserted,
245 or ``0`` if the key was not present and *default_value* was inserted.
246 On failure, returns ``-1``, sets an exception, and sets ``*result``
247 to ``NULL``.
248
249 For clarity: if you have a strong reference to *default_value* before
250 calling this function, then after it returns, you hold a strong reference
251 to both *default_value* and *\*result* (if it's not ``NULL``).
252 These may refer to the same object: in that case you hold two separate
253 references to it.
254
255 .. note::
256
257 The operation is atomic on :term:`free threading <free-threaded build>`
258 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
259
260 .. versionadded:: 3.13
261
262
263 .. c:function:: int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)
264
265 Remove *key* from dictionary *p* and optionally return the removed value.
266 Do not raise :exc:`KeyError` if the key is missing.
267
268 - If the key is present, set *\*result* to a new reference to the removed
269 value if *result* is not ``NULL``, and return ``1``.
270 - If the key is missing, set *\*result* to ``NULL`` if *result* is not
271 ``NULL``, and return ``0``.
272 - On error, raise an exception and return ``-1``.
273
274 Similar to :meth:`dict.pop`, but without the default value and
275 not raising :exc:`KeyError` if the key is missing.
276
277 .. note::
278
279 The operation is atomic on :term:`free threading <free-threaded build>`
280 when *key* is :class:`str`, :class:`int`, :class:`float`, :class:`bool` or :class:`bytes`.
281
282 .. versionadded:: 3.13
283
284
285 .. c:function:: int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
286
287 Similar to :c:func:`PyDict_Pop`, but *key* is specified as a
288 :c:expr:`const char*` UTF-8 encoded bytes string, rather than a
289 :c:expr:`PyObject*`.
290
291 .. versionadded:: 3.13
292
293
294 .. c:function:: PyObject* PyDict_Items(PyObject *p)
295
296 Return a :c:type:`PyListObject` containing all the items from the dictionary.
297
298
299 .. c:function:: PyObject* PyDict_Keys(PyObject *p)
300
301 Return a :c:type:`PyListObject` containing all the keys from the dictionary.
302
303
304 .. c:function:: PyObject* PyDict_Values(PyObject *p)
305
306 Return a :c:type:`PyListObject` containing all the values from the dictionary
307 *p*.
308
309
310 .. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
311
312 .. index:: pair: built-in function; len
313
314 Return the number of items in the dictionary. This is equivalent to
315 ``len(p)`` on a dictionary.
316
317
318 .. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p)
319
320 Similar to :c:func:`PyDict_Size`, but without error checking.
321
322
323 .. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
324
325 Iterate over all key-value pairs in the dictionary *p*. The
326 :c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
327 prior to the first call to this function to start the iteration; the
328 function returns true for each pair in the dictionary, and false once all
329 pairs have been reported. The parameters *pkey* and *pvalue* should either
330 point to :c:expr:`PyObject*` variables that will be filled in with each key
331 and value, respectively, or may be ``NULL``. Any references returned through
332 them are borrowed. *ppos* should not be altered during iteration. Its
333 value represents offsets within the internal dictionary structure, and
334 since the structure is sparse, the offsets are not consecutive.
335
336 For example::
337
338 PyObject *key, *value;
339 Py_ssize_t pos = 0;
340
341 while (PyDict_Next(self->dict, &pos, &key, &value)) {
342 /* do something interesting with the values... */
343 ...
344 }
345
346 The dictionary *p* should not be mutated during iteration. It is safe to
347 modify the values of the keys as you iterate over the dictionary, but only
348 so long as the set of keys does not change. For example::
349
350 PyObject *key, *value;
351 Py_ssize_t pos = 0;
352
353 while (PyDict_Next(self->dict, &pos, &key, &value)) {
354 long i = PyLong_AsLong(value);
355 if (i == -1 && PyErr_Occurred()) {
356 return -1;
357 }
358 PyObject *o = PyLong_FromLong(i + 1);
359 if (o == NULL)
360 return -1;
361 if (PyDict_SetItem(self->dict, key, o) < 0) {
362 Py_DECREF(o);
363 return -1;
364 }
365 Py_DECREF(o);
366 }
367
368 The function is not thread-safe in the :term:`free-threaded <free threading>`
369 build without external synchronization. You can use
370 :c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating
371 over it::
372
373 Py_BEGIN_CRITICAL_SECTION(self->dict);
374 while (PyDict_Next(self->dict, &pos, &key, &value)) {
375 ...
376 }
377 Py_END_CRITICAL_SECTION();
378
379 .. note::
380
381 On the free-threaded build, this function can be used safely inside a
382 critical section. However, the references returned for *pkey* and *pvalue*
383 are :term:`borrowed <borrowed reference>` and are only valid while the
384 critical section is held. If you need to use these objects outside the
385 critical section or when the critical section can be suspended, create a
386 :term:`strong reference <strong reference>` (for example, using
387 :c:func:`Py_NewRef`).
388
389 .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
390
391 Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
392 *b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
393 and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
394 will be replaced if a matching key is found in *b*, otherwise pairs will
395 only be added if there is not a matching key in *a*. Return ``0`` on
396 success or ``-1`` if an exception was raised.
397
398 .. note::
399
400 In the :term:`free-threaded build`, when *b* is a
401 :class:`dict` (with the standard iterator), both *a* and *b* are locked
402 for the duration of the operation. When *b* is a non-dict mapping, only
403 *a* is locked; *b* may be concurrently modified by another thread.
404
405
406 .. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
407
408 This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
409 ``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
410 back to the iterating over a sequence of key value pairs if the second
411 argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an
412 exception was raised.
413
414 .. note::
415
416 In the :term:`free-threaded build`, when *b* is a
417 :class:`dict` (with the standard iterator), both *a* and *b* are locked
418 for the duration of the operation. When *b* is a non-dict mapping, only
419 *a* is locked; *b* may be concurrently modified by another thread.
420
421
422 .. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
423
424 Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
425 *seq2* must be an iterable object producing iterable objects of length 2,
426 viewed as key-value pairs. In case of duplicate keys, the last wins if
427 *override* is true, else the first wins. Return ``0`` on success or ``-1``
428 if an exception was raised. Equivalent Python (except for the return
429 value)::
430
431 def PyDict_MergeFromSeq2(a, seq2, override):
432 for key, value in seq2:
433 if override or key not in a:
434 a[key] = value
435
436 .. note::
437
438 In the :term:`free-threaded <free threading>` build, only *a* is locked.
439 The iteration over *seq2* is not synchronized; *seq2* may be concurrently
440 modified by another thread.
441
442
443 .. c:function:: int PyDict_AddWatcher(PyDict_WatchCallback callback)
444
445 Register *callback* as a dictionary watcher. Return a non-negative integer
446 id which must be passed to future calls to :c:func:`PyDict_Watch`. In case
447 of error (e.g. no more watcher IDs available), return ``-1`` and set an
448 exception.
449
450 .. note::
451
452 This function is not internally synchronized. In the
453 :term:`free-threaded <free threading>` build, callers should ensure no
454 concurrent calls to :c:func:`PyDict_AddWatcher` or
455 :c:func:`PyDict_ClearWatcher` are in progress.
456
457 .. versionadded:: 3.12
458
459 .. c:function:: int PyDict_ClearWatcher(int watcher_id)
460
461 Clear watcher identified by *watcher_id* previously returned from
462 :c:func:`PyDict_AddWatcher`. Return ``0`` on success, ``-1`` on error (e.g.
463 if the given *watcher_id* was never registered.)
464
465 .. note::
466
467 This function is not internally synchronized. In the
468 :term:`free-threaded <free threading>` build, callers should ensure no
469 concurrent calls to :c:func:`PyDict_AddWatcher` or
470 :c:func:`PyDict_ClearWatcher` are in progress.
471
472 .. versionadded:: 3.12
473
474 .. c:function:: int PyDict_Watch(int watcher_id, PyObject *dict)
475
476 Mark dictionary *dict* as watched. The callback granted *watcher_id* by
477 :c:func:`PyDict_AddWatcher` will be called when *dict* is modified or
478 deallocated. Return ``0`` on success or ``-1`` on error.
479
480 .. versionadded:: 3.12
481
482 .. c:function:: int PyDict_Unwatch(int watcher_id, PyObject *dict)
483
484 Mark dictionary *dict* as no longer watched. The callback granted
485 *watcher_id* by :c:func:`PyDict_AddWatcher` will no longer be called when
486 *dict* is modified or deallocated. The dict must previously have been
487 watched by this watcher. Return ``0`` on success or ``-1`` on error.
488
489 .. versionadded:: 3.12
490
491 .. c:type:: PyDict_WatchEvent
492
493 Enumeration of possible dictionary watcher events: ``PyDict_EVENT_ADDED``,
494 ``PyDict_EVENT_MODIFIED``, ``PyDict_EVENT_DELETED``, ``PyDict_EVENT_CLONED``,
495 ``PyDict_EVENT_CLEARED``, or ``PyDict_EVENT_DEALLOCATED``.
496
497 .. versionadded:: 3.12
498
499 .. c:type:: int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)
500
501 Type of a dict watcher callback function.
502
503 If *event* is ``PyDict_EVENT_CLEARED`` or ``PyDict_EVENT_DEALLOCATED``, both
504 *key* and *new_value* will be ``NULL``. If *event* is ``PyDict_EVENT_ADDED``
505 or ``PyDict_EVENT_MODIFIED``, *new_value* will be the new value for *key*.
506 If *event* is ``PyDict_EVENT_DELETED``, *key* is being deleted from the
507 dictionary and *new_value* will be ``NULL``.
508
509 ``PyDict_EVENT_CLONED`` occurs when *dict* was previously empty and another
510 dict is merged into it. To maintain efficiency of this operation, per-key
511 ``PyDict_EVENT_ADDED`` events are not issued in this case; instead a
512 single ``PyDict_EVENT_CLONED`` is issued, and *key* will be the source
513 dictionary.
514
515 The callback may inspect but must not modify *dict*; doing so could have
516 unpredictable effects, including infinite recursion. Do not trigger Python
517 code execution in the callback, as it could modify the dict as a side effect.
518
519 If *event* is ``PyDict_EVENT_DEALLOCATED``, taking a new reference in the
520 callback to the about-to-be-destroyed dictionary will resurrect it and
521 prevent it from being freed at this time. When the resurrected object is
522 destroyed later, any watcher callbacks active at that time will be called
523 again.
524
525 Callbacks occur before the notified modification to *dict* takes place, so
526 the prior state of *dict* can be inspected.
527
528 If the callback sets an exception, it must return ``-1``; this exception will
529 be printed as an unraisable exception using :c:func:`PyErr_WriteUnraisable`.
530 Otherwise it should return ``0``.
531
532 There may already be a pending exception set on entry to the callback. In
533 this case, the callback should return ``0`` with the same exception still
534 set. This means the callback may not call any other API that can set an
535 exception unless it saves and clears the exception state first, and restores
536 it before returning.
537
538 .. versionadded:: 3.12
539
540
541 Dictionary View Objects
542 ^^^^^^^^^^^^^^^^^^^^^^^
543
544 .. c:function:: int PyDictViewSet_Check(PyObject *op)
545
546 Return true if *op* is a view of a set inside a dictionary. This is currently
547 equivalent to :c:expr:`PyDictKeys_Check(op) || PyDictItems_Check(op)`. This
548 function always succeeds.
549
550
551 .. c:var:: PyTypeObject PyDictKeys_Type
552
553 Type object for a view of dictionary keys. In Python, this is the type of
554 the object returned by :meth:`dict.keys`.
555
556
557 .. c:function:: int PyDictKeys_Check(PyObject *op)
558
559 Return true if *op* is an instance of a dictionary keys view. This function
560 always succeeds.
561
562
563 .. c:var:: PyTypeObject PyDictValues_Type
564
565 Type object for a view of dictionary values. In Python, this is the type of
566 the object returned by :meth:`dict.values`.
567
568
569 .. c:function:: int PyDictValues_Check(PyObject *op)
570
571 Return true if *op* is an instance of a dictionary values view. This function
572 always succeeds.
573
574
575 .. c:var:: PyTypeObject PyDictItems_Type
576
577 Type object for a view of dictionary items. In Python, this is the type of
578 the object returned by :meth:`dict.items`.
579
580
581 .. c:function:: int PyDictItems_Check(PyObject *op)
582
583 Return true if *op* is an instance of a dictionary items view. This function
584 always succeeds.
585
586
587 Ordered Dictionaries
588 ^^^^^^^^^^^^^^^^^^^^
589
590 Python's C API provides interface for :class:`collections.OrderedDict` from C.
591 Since Python 3.7, dictionaries are ordered by default, so there is usually
592 little need for these functions; prefer ``PyDict*`` where possible.
593
594
595 .. c:var:: PyTypeObject PyODict_Type
596
597 Type object for ordered dictionaries. This is the same object as
598 :class:`collections.OrderedDict` in the Python layer.
599
600
601 .. c:function:: int PyODict_Check(PyObject *od)
602
603 Return true if *od* is an ordered dictionary object or an instance of a
604 subtype of the :class:`~collections.OrderedDict` type. This function
605 always succeeds.
606
607
608 .. c:function:: int PyODict_CheckExact(PyObject *od)
609
610 Return true if *od* is an ordered dictionary object, but not an instance of
611 a subtype of the :class:`~collections.OrderedDict` type.
612 This function always succeeds.
613
614
615 .. c:var:: PyTypeObject PyODictKeys_Type
616
617 Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries.
618
619
620 .. c:var:: PyTypeObject PyODictValues_Type
621
622 Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries.
623
624
625 .. c:var:: PyTypeObject PyODictItems_Type
626
627 Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries.
628
629
630 .. c:function:: PyObject *PyODict_New(void)
631
632 Return a new empty ordered dictionary, or ``NULL`` on failure.
633
634 This is analogous to :c:func:`PyDict_New`.
635
636
637 .. c:function:: int PyODict_SetItem(PyObject *od, PyObject *key, PyObject *value)
638
639 Insert *value* into the ordered dictionary *od* with a key of *key*.
640 Return ``0`` on success or ``-1`` with an exception set on failure.
641
642 This is analogous to :c:func:`PyDict_SetItem`.
643
644
645 .. c:function:: int PyODict_DelItem(PyObject *od, PyObject *key)
646
647 Remove the entry in the ordered dictionary *od* with key *key*.
648 Return ``0`` on success or ``-1`` with an exception set on failure.
649
650 This is analogous to :c:func:`PyDict_DelItem`.
651
652
653 These are :term:`soft deprecated` aliases to ``PyDict`` APIs:
654
655
656 .. list-table::
657 :widths: auto
658 :header-rows: 1
659
660 * * ``PyODict``
661 * ``PyDict``
662 * * .. c:macro:: PyODict_GetItem(od, key)
663 * :c:func:`PyDict_GetItem`
664 * * .. c:macro:: PyODict_GetItemWithError(od, key)
665 * :c:func:`PyDict_GetItemWithError`
666 * * .. c:macro:: PyODict_GetItemString(od, key)
667 * :c:func:`PyDict_GetItemString`
668 * * .. c:macro:: PyODict_Contains(od, key)
669 * :c:func:`PyDict_Contains`
670 * * .. c:macro:: PyODict_Size(od)
671 * :c:func:`PyDict_Size`
672 * * .. c:macro:: PyODict_SIZE(od)
673 * :c:func:`PyDict_GET_SIZE`