From f3950f206dfd3edcea79b2b01b63bf6ad0e9dc9c Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 6 Nov 2025 08:04:55 -0500 Subject: [PATCH 1/6] Document PyODict --- Doc/c-api/dict.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 246ce5391e142c..4788711995cbcf 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -431,3 +431,91 @@ Dictionary Objects it before returning. .. versionadded:: 3.12 + + +Ordered Dictionaries +^^^^^^^^^^^^^^^^^^^^ + +Python's C API provides interface for :class:`collections.OrderedDict` from C. +These APIs are mostly redundant; 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. + + Since Python 3.7, dictionaries are ordered by default, so there is usually + little need for this object. + + +.. 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 a dict 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_GET_SIZE` From 154beaa0d56976d2162786ca8168e2a197f6b683 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 6 Nov 2025 08:06:43 -0500 Subject: [PATCH 2/6] Document the iterator type. --- Doc/c-api/iterator.rst | 1 + 1 file changed, 1 insertion(+) 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. From fb2555eb8fe6a2f35df5f7fa1ad3f723c8643080 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 17:50:40 -0500 Subject: [PATCH 3/6] Move obsoleteness note to introductory paragraph. --- Doc/c-api/dict.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index a99825cbc610ac..38cd68af09226e 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -483,7 +483,8 @@ Ordered Dictionaries ^^^^^^^^^^^^^^^^^^^^ Python's C API provides interface for :class:`collections.OrderedDict` from C. -These APIs are mostly redundant; prefer ``PyDict*`` where possible. +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 @@ -491,9 +492,6 @@ These APIs are mostly redundant; prefer ``PyDict*`` where possible. Type object for ordered dictionaries. This is the same object as :class:`collections.OrderedDict` in the Python layer. - Since Python 3.7, dictionaries are ordered by default, so there is usually - little need for this object. - .. c:function:: int PyODict_Check(PyObject *od) From c4bd239258d96707f69c19ad0570f22d15906251 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 17:51:24 -0500 Subject: [PATCH 4/6] Add docs for PyDict_Size(). --- Doc/c-api/dict.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 38cd68af09226e..d105cb4fe90695 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -561,5 +561,7 @@ These are :term:`soft deprecated` aliases to ``PyDict`` APIs: * :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` From b69ecacf4cc9acb33dc0334b34232b74671fba96 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 17:51:43 -0500 Subject: [PATCH 5/6] Remove leading ! in Sphinx refs. These are documented now so we can link to them. --- Doc/c-api/dict.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index d105cb4fe90695..c863accbec683a 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -508,17 +508,17 @@ little need for these functions; prefer ``PyDict*`` where possible. .. c:var:: PyTypeObject PyODictKeys_Type - Analogous to :c:type:`!PyDictKeys_Type` for ordered dictionaries. + Analogous to :c:type:`PyDictKeys_Type` for ordered dictionaries. .. c:var:: PyTypeObject PyODictValues_Type - Analogous to :c:type:`!PyDictValues_Type` for ordered dictionaries. + Analogous to :c:type:`PyDictValues_Type` for ordered dictionaries. .. c:var:: PyTypeObject PyODictItems_Type - Analogous to :c:type:`!PyDictItems_Type` for ordered dictionaries. + Analogous to :c:type:`PyDictItems_Type` for ordered dictionaries. .. c:function:: PyObject *PyODict_New(void) From fcaf638d6d8cde7c5819fb40f853f28908470f99 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 13 Nov 2025 17:52:34 -0500 Subject: [PATCH 6/6] Fix PyODict_CheckExact() description. --- Doc/c-api/dict.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index c863accbec683a..ede1699cfeb653 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -502,8 +502,9 @@ little need for these functions; prefer ``PyDict*`` where possible. .. c:function:: int PyODict_CheckExact(PyObject *od) - Return true if *od* is a dict object, but not an instance of a subtype of - the :class:`~collections.OrderedDict` type. This function always succeeds. + 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