https://github.com/python/cpython/commit/b3626321b6ebb46dd24acee2aa806450e70febfc
commit: b3626321b6ebb46dd24acee2aa806450e70febfc
branch: main
author: Peter Bierma <[email protected]>
committer: ZeroIntensity <[email protected]>
date: 2025-11-17T14:40:47-05:00
summary:
gh-141004: Document `PyODict*` APIs (GH-141136)
files:
M Doc/c-api/dict.rst
M Doc/c-api/iterator.rst
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index b7f201811aad6c..ede1699cfeb653 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -477,3 +477,92 @@ Dictionary View Objects
Return true if *op* is an instance of a dictionary items view. This function
always succeeds.
+
+
+Ordered Dictionaries
+^^^^^^^^^^^^^^^^^^^^
+
+Python's C API provides interface for :class:`collections.OrderedDict` from C.
+Since Python 3.7, dictionaries are ordered by default, so there is usually
+little need for these functions; prefer ``PyDict*`` where possible.
+
+
+.. c:var:: PyTypeObject PyODict_Type
+
+ Type object for ordered dictionaries. This is the same object as
+ :class:`collections.OrderedDict` in the Python layer.
+
+
+.. c:function:: int PyODict_Check(PyObject *od)
+
+ Return true if *od* is an ordered dictionary object or an instance of a
+ subtype of the :class:`~collections.OrderedDict` type. This function
+ always succeeds.
+
+
+.. c:function:: int PyODict_CheckExact(PyObject *od)
+
+ Return true if *od* is an ordered dictionary object, but not an instance of
+ a subtype of the :class:`~collections.OrderedDict` type.
+ This function always succeeds.
+
+
+.. c:var:: PyTypeObject PyODictKeys_Type
+
+ Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries.
+
+
+.. c:var:: PyTypeObject PyODictValues_Type
+
+ Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries.
+
+
+.. c:var:: PyTypeObject PyODictItems_Type
+
+ Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries.
+
+
+.. c:function:: PyObject *PyODict_New(void)
+
+ Return a new empty ordered dictionary, or ``NULL`` on failure.
+
+ This is analogous to :c:func:`PyDict_New`.
+
+
+.. c:function:: int PyODict_SetItem(PyObject *od, PyObject *key, PyObject
*value)
+
+ Insert *value* into the ordered dictionary *od* with a key of *key*.
+ Return ``0`` on success or ``-1`` with an exception set on failure.
+
+ This is analogous to :c:func:`PyDict_SetItem`.
+
+
+.. c:function:: int PyODict_DelItem(PyObject *od, PyObject *key)
+
+ Remove the entry in the ordered dictionary *od* with key *key*.
+ Return ``0`` on success or ``-1`` with an exception set on failure.
+
+ This is analogous to :c:func:`PyDict_DelItem`.
+
+
+These are :term:`soft deprecated` aliases to ``PyDict`` APIs:
+
+
+.. list-table::
+ :widths: auto
+ :header-rows: 1
+
+ * * ``PyODict``
+ * ``PyDict``
+ * * .. c:macro:: PyODict_GetItem(od, key)
+ * :c:func:`PyDict_GetItem`
+ * * .. c:macro:: PyODict_GetItemWithError(od, key)
+ * :c:func:`PyDict_GetItemWithError`
+ * * .. c:macro:: PyODict_GetItemString(od, key)
+ * :c:func:`PyDict_GetItemString`
+ * * .. c:macro:: PyODict_Contains(od, key)
+ * :c:func:`PyDict_Contains`
+ * * .. c:macro:: PyODict_Size(od)
+ * :c:func:`PyDict_Size`
+ * * .. c:macro:: PyODict_SIZE(od)
+ * :c:func:`PyDict_GET_SIZE`
diff --git a/Doc/c-api/iterator.rst b/Doc/c-api/iterator.rst
index 7eaf72ec55fd77..bfbfe3c9279980 100644
--- a/Doc/c-api/iterator.rst
+++ b/Doc/c-api/iterator.rst
@@ -108,6 +108,7 @@ Other Iterator Objects
.. c:var:: PyTypeObject PyDictRevIterValue_Type
.. c:var:: PyTypeObject PyDictIterItem_Type
.. c:var:: PyTypeObject PyDictRevIterItem_Type
+.. c:var:: PyTypeObject PyODictIter_Type
Type objects for iterators of various built-in objects.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
