gh-141510: Update PyDict C API doc for frozendict (#145533)

Mention frozendict support.

diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index d63c26865899cc142840a0872f5d87921155e52d..f44c18e80758bb6b6ff5bb8b4dc89ce32baf0282 100644 (file)
--- 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*.