From 847567f1bfc2c059e8a8069d4d5d3244fbf17884 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 5 Mar 2026 13:09:06 +0100 Subject: [PATCH 1/3] gh-141510: Update PyDict C API doc for frozendict Mention frozendict support. --- Doc/c-api/dict.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 734462bc0051af..6ce1c6abf3d217 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -42,6 +42,9 @@ Dictionary objects enforces read-only behavior. This is normally used to create a view to prevent modification of the dictionary for non-dynamic class types. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:var:: PyTypeObject PyDictProxy_Type @@ -77,6 +80,9 @@ Dictionary objects .. versionadded:: 3.13 + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_Copy(PyObject *p) @@ -128,6 +134,9 @@ Dictionary objects .. versionadded:: 3.13 + .. versionchanged:: next + Accept also :class:`frozendict`. + See also the :c:func:`PyObject_GetItem` function. @@ -147,6 +156,9 @@ Dictionary objects Calling this API without an :term:`attached thread state` had been allowed for historical reason. It is no longer allowed. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key) @@ -155,6 +167,9 @@ Dictionary objects occurred. Return ``NULL`` **without** an exception set if the key wasn't present. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) @@ -170,6 +185,9 @@ Dictionary objects Prefer using the :c:func:`PyDict_GetItemWithError` function with your own :c:func:`PyUnicode_FromString` *key* instead. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result) @@ -179,6 +197,9 @@ Dictionary objects .. versionadded:: 3.13 + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj) @@ -242,17 +263,26 @@ Dictionary objects Return a :c:type:`PyListObject` containing all the items from the dictionary. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_Keys(PyObject *p) Return a :c:type:`PyListObject` containing all the keys from the dictionary. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: PyObject* PyDict_Values(PyObject *p) Return a :c:type:`PyListObject` containing all the values from the dictionary *p*. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: Py_ssize_t PyDict_Size(PyObject *p) @@ -261,11 +291,17 @@ Dictionary objects Return the number of items in the dictionary. This is equivalent to ``len(p)`` on a dictionary. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p) Similar to :c:func:`PyDict_Size`, but without error checking. + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue) @@ -333,6 +369,9 @@ Dictionary objects :term:`strong reference ` (for example, using :c:func:`Py_NewRef`). + .. versionchanged:: next + Accept also :class:`frozendict`. + .. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override) Iterate over mapping object *b* adding key-value pairs to dictionary *a*. From 0119335c19db0615d1af00212dd780b9c7e1b726 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 5 Mar 2026 15:48:18 +0100 Subject: [PATCH 2/3] Mention also frozendict in the doc body --- Doc/c-api/dict.rst | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 6ce1c6abf3d217..b21da28e108603 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -42,6 +42,9 @@ Dictionary objects enforces read-only behavior. This is normally used to create a view to prevent modification of the dictionary for non-dynamic class types. + The first argument can be a :class:`dict`, a :class:`frozendict`, or a + mapping. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -71,6 +74,11 @@ Dictionary objects *key*, return ``1``, otherwise return ``0``. On error, return ``-1``. This is equivalent to the Python expression ``key in p``. + The first argument can be a :class:`dict` or a :class:`frozendict`. + + .. versionchanged:: next + Also accept :class:`frozendict`. + .. c:function:: int PyDict_ContainsString(PyObject *p, const char *key) @@ -78,6 +86,8 @@ Dictionary objects :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionadded:: 3.13 .. versionchanged:: next @@ -88,10 +98,6 @@ Dictionary objects Return a new dictionary that contains the same key-value pairs as *p*. - .. versionchanged:: next - If *p* is a subclass of :class:`frozendict`, the result will be a - :class:`frozendict` instance instead of a :class:`dict` instance. - .. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val) Insert *val* into the dictionary *p* with a key of *key*. *key* must be @@ -132,6 +138,8 @@ Dictionary objects * If the key is missing, set *\*result* to ``NULL`` and return ``0``. * On error, raise an exception and return ``-1``. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionadded:: 3.13 .. versionchanged:: next @@ -146,6 +154,8 @@ Dictionary objects has a key *key*. Return ``NULL`` if the key *key* is missing *without* setting an exception. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. note:: Exceptions that occur while this calls :meth:`~object.__hash__` and @@ -167,6 +177,8 @@ Dictionary objects occurred. Return ``NULL`` **without** an exception set if the key wasn't present. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -177,6 +189,8 @@ Dictionary objects :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. note:: Exceptions that occur while this calls :meth:`~object.__hash__` and @@ -195,6 +209,8 @@ Dictionary objects :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionadded:: 3.13 .. versionchanged:: next @@ -263,6 +279,8 @@ Dictionary objects Return a :c:type:`PyListObject` containing all the items from the dictionary. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -271,6 +289,8 @@ Dictionary objects Return a :c:type:`PyListObject` containing all the keys from the dictionary. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -280,6 +300,8 @@ Dictionary objects Return a :c:type:`PyListObject` containing all the values from the dictionary *p*. + The first argument can be a :class:`dict` or a :class:`frozendict`. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -291,6 +313,8 @@ Dictionary objects Return the number of items in the dictionary. This is equivalent to ``len(p)`` on a dictionary. + The argument can be a :class:`dict` or a :class:`frozendict`. + .. versionchanged:: next Accept also :class:`frozendict`. @@ -316,6 +340,8 @@ Dictionary objects value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. + The first argument can be a :class:`dict` or a :class:`frozendict`. + For example:: PyObject *key, *value; From 48d359164f49d8b8e435f77d56379c3a605a2a3f Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 5 Mar 2026 17:59:37 +0100 Subject: [PATCH 3/3] Remove redundant information --- Doc/c-api/dict.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index b21da28e108603..789086cbcce62c 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -177,8 +177,6 @@ Dictionary objects occurred. Return ``NULL`` **without** an exception set if the key wasn't present. - The first argument can be a :class:`dict` or a :class:`frozendict`. - .. versionchanged:: next Accept also :class:`frozendict`. @@ -189,8 +187,6 @@ Dictionary objects :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. - The first argument can be a :class:`dict` or a :class:`frozendict`. - .. note:: Exceptions that occur while this calls :meth:`~object.__hash__` and @@ -209,8 +205,6 @@ Dictionary objects :c:expr:`const char*` UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. - The first argument can be a :class:`dict` or a :class:`frozendict`. - .. versionadded:: 3.13 .. versionchanged:: next