https://github.com/python/cpython/commit/d4cc553294a558d632a2f69523eb04fa8c51f1a7
commit: d4cc553294a558d632a2f69523eb04fa8c51f1a7
branch: main
author: Victor Stinner <[email protected]>
committer: vstinner <[email protected]>
date: 2026-03-12T15:04:36+01:00
summary:
gh-141510: Update PyDict C API doc for frozendict (#145533)
Mention frozendict support.
files:
M Doc/c-api/dict.rst
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index d63c26865899cc..f44c18e80758bb 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -42,6 +42,12 @@ 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
+ Also accept :class:`frozendict`.
+
.. c:var:: PyTypeObject PyDictProxy_Type
@@ -68,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)
@@ -75,8 +86,13 @@ 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
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
@@ -122,8 +138,13 @@ 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
+ Also accept :class:`frozendict`.
+
See also the :c:func:`PyObject_GetItem` function.
@@ -133,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
@@ -143,6 +166,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
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
@@ -151,6 +177,9 @@ Dictionary objects
occurred. Return ``NULL`` **without** an exception set if the key
wasn't present.
+ .. versionchanged:: next
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
@@ -166,6 +195,9 @@ Dictionary objects
Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
:c:func:`PyUnicode_FromString` *key* instead.
+ .. versionchanged:: next
+ Also accept :class:`frozendict`.
+
.. c:function:: int PyDict_GetItemStringRef(PyObject *p, const char *key,
PyObject **result)
@@ -175,6 +207,9 @@ Dictionary objects
.. versionadded:: 3.13
+ .. versionchanged:: next
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key,
PyObject *defaultobj)
@@ -238,17 +273,32 @@ 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
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
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
+ Also accept :class:`frozendict`.
+
.. c:function:: PyObject* PyDict_Values(PyObject *p)
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
+ Also accept :class:`frozendict`.
+
.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
@@ -257,11 +307,19 @@ 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
+ Also accept :class:`frozendict`.
+
.. c:function:: Py_ssize_t PyDict_GET_SIZE(PyObject *p)
Similar to :c:func:`PyDict_Size`, but without error checking.
+ .. versionchanged:: next
+ Also accept :class:`frozendict`.
+
.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject
**pkey, PyObject **pvalue)
@@ -276,6 +334,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;
@@ -309,7 +369,7 @@ Dictionary objects
}
The function is not thread-safe in the :term:`free-threaded <free
threading>`
- build without external synchronization. You can use
+ build without external synchronization for a mutable :class:`dict`. You can
use
:c:macro:`Py_BEGIN_CRITICAL_SECTION` to lock the dictionary while iterating
over it::
@@ -319,6 +379,8 @@ Dictionary objects
}
Py_END_CRITICAL_SECTION();
+ The function is thread-safe on a :class:`frozendict`.
+
.. note::
On the free-threaded build, this function can be used safely inside a
@@ -329,6 +391,9 @@ Dictionary objects
:term:`strong reference <strong reference>` (for example, using
:c:func:`Py_NewRef`).
+ .. versionchanged:: next
+ Also accept :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*.
_______________________________________________
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]
