gh-141510, PEP 814: Add built-in frozendict type

Doc/c-api/dict.rst

@@ -490,6 +490,55 @@ Dictionary View Objects
    always succeeds.
 
 
+Frozen Dictionary Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: next
+
+
+.. c:var:: PyTypeObject PyFrozenDict_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python frozen
+   dictionary type.
+   This is the same object as :class:`frozendict` in the Python layer.
+
+
+.. c:function:: int PyAnyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object, a frozendict object, or an instance of
+   a subtype of the dict or frozendict type.
+   This function always succeeds.
+
+
+.. c:function:: int PyAnyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object or a frozendict object, but not an
+   instance of a subtype of the dict or frozendict type.
+   This function always succeeds.
+
+
+.. c:function:: int PyFrozenDict_Check(PyObject *p)
+
+   Return true if *p* is a frozendict object or an instance of a subtype of the
+   frozendict type.
+   This function always succeeds.
+
+
+.. c:function:: int PyFrozenDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a frozendict object, but not an instance of a subtype
+   of the frozendict type.
+   This function always succeeds.
+
+
+.. c:function:: PyObject* PyFrozenDict_New(PyObject *iterable)
+
+   Return a new frozendict from an iterable, or ``NULL`` on failure with an
+   exception set.
+
+   Create an empty dictionary if *iterable* is ``NULL``.
+
+
 Ordered Dictionaries
 ^^^^^^^^^^^^^^^^^^^^
 

Doc/library/stdtypes.rst

@@ -5305,8 +5305,8 @@
 
 .. _typesmapping:
 
-Mapping Types --- :class:`dict`
-===============================
+Mapping Types --- :class:`dict`, :class:`frozendict`
+====================================================
 
 .. index::
    pair: object; mapping
@@ -5317,8 +5317,9 @@
    pair: built-in function; len
 
 A :term:`mapping` object maps :term:`hashable` values to arbitrary objects.
-Mappings are mutable objects.  There is currently only one standard mapping
-type, the :dfn:`dictionary`.  (For other containers see the built-in
+There are currently two standard mapping types, the :dfn:`dictionary` and
+:class:`frozendict`.
+(For other containers see the built-in
 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
 :mod:`collections` module.)
 
@@ -5588,10 +5589,9 @@
       Dictionaries are now reversible.
 
 
-.. seealso::
-   :class:`types.MappingProxyType` can be used to create a read-only view
-   of a :class:`dict`.
-
+   .. seealso::
+      :class:`types.MappingProxyType` can be used to create a read-only view
+      of a :class:`dict`.
 
 .. _thread-safety-dict:
 
@@ -5839,6 +5839,35 @@
    500
 
 
+.. class:: frozendict(**kwargs)
+           frozendict(mapping, /, **kwargs)
+           frozendict(iterable, /, **kwargs)
+
+   Return a new frozen dictionary initialized from an optional positional
+   argument and a possibly empty set of keyword arguments.
+
+   A frozendict has a similar API than the :class:`dict` API, with the
+   following differences:
+
+   * :class:`dict` has more methods than :class:`frozendict`:
+
+      * :meth:`~!dict.__delitem__`
+      * :meth:`~!dict.__setitem__`
+      * :meth:`~dict.clear`
+      * :meth:`~dict.pop`
+      * :meth:`~dict.popitem`
+      * :meth:`~dict.setdefault`
+      * :meth:`~dict.update`
+
+   * A frozendict can be hashed with ``hash(frozendict)`` if all keys and
+     values can be hashed.
+
+   * ``frozendict |= other`` does not modify the frozendict in-place but
+     creates a new frozen dictionary.
+
+   .. versionadded:: next
+
+
 .. _typecontextmanager:
 
 Context Manager Types
@@ -6062,6 +6091,7 @@
 * :class:`list`
 * :class:`dict`
 * :class:`set`
+* :class:`frozendict`
 * :class:`frozenset`
 * :class:`type`
 * :class:`asyncio.Future`

Doc/whatsnew/3.15.rst

@@ -65,6 +65,8 @@ Summary -- Release highlights
 
 .. PEP-sized items next.
 
+* :pep:`814`: :ref:`Add frozendict built-in type
+  <whatsnew315-pep814>`
 * :pep:`810`: :ref:`Explicit lazy imports for faster startup times
   <whatsnew315-pep810>`
 * :pep:`799`: :ref:`A dedicated profiling package for organizing Python
@@ -84,6 +86,20 @@ Summary -- Release highlights
 New features
 ============
 
+.. _whatsnew315-pep814:
+
+:pep:`814`: Add frozendict built-in type
+----------------------------------------
+
+A new public immutable type :class:`frozendict` is added to the :mod:`builtins`
+module. It is not a ``dict`` subclass but inherits directly from ``object``.
+
+A ``frozendict`` can be hashed with ``hash(frozendict)`` if all keys and values
+can be hashed.
+
+.. seealso:: :pep:`814` for the full specification and rationale.
+
+
 .. _whatsnew315-pep810:
 
 :pep:`810`: Explicit lazy imports
@@ -1512,6 +1528,16 @@ C API changes
 New features
 ------------
 
+* Add the following functions for the new :class:`frozendict` type:
+
+  * :c:func:`PyAnyDict_Check`
+  * :c:func:`PyAnyDict_CheckExact`
+  * :c:func:`PyFrozenDict_Check`
+  * :c:func:`PyFrozenDict_CheckExact`
+  * :c:func:`PyFrozenDict_New`
+
+  (Contributed by Victor Stinner in :gh:`141510`.)
+
 * Add :c:func:`PySys_GetAttr`, :c:func:`PySys_GetAttrString`,
   :c:func:`PySys_GetOptionalAttr`, and :c:func:`PySys_GetOptionalAttrString`
   functions as replacements for :c:func:`PySys_GetObject`.

Include/cpython/dictobject.h

@@ -32,6 +32,16 @@ typedef struct {
     PyDictValues *ma_values;
 } PyDictObject;
 
+// frozendict
+PyAPI_DATA(PyTypeObject) PyFrozenDict_Type;
+#define PyFrozenDict_Check(op) PyObject_TypeCheck((op), &PyFrozenDict_Type)
+#define PyFrozenDict_CheckExact(op) Py_IS_TYPE((op), &PyFrozenDict_Type)
+
+#define PyAnyDict_CheckExact(ob) \
+    (PyDict_CheckExact(ob) || PyFrozenDict_CheckExact(ob))
+#define PyAnyDict_Check(ob) \
+    (PyDict_Check(ob) || PyFrozenDict_Check(ob))
+
 PyAPI_FUNC(PyObject *) _PyDict_GetItem_KnownHash(PyObject *mp, PyObject *key,
                                                  Py_hash_t hash);
 // PyDict_GetItemStringRef() can be used instead
@@ -42,7 +52,7 @@ PyAPI_FUNC(PyObject *) PyDict_SetDefault(
 /* Get the number of items of a dictionary. */
 static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
     PyDictObject *mp;
-    assert(PyDict_Check(op));
+    assert(PyAnyDict_Check(op));
     mp = _Py_CAST(PyDictObject*, op);
 #ifdef Py_GIL_DISABLED
     return _Py_atomic_load_ssize_relaxed(&mp->ma_used);
@@ -93,3 +103,6 @@ PyAPI_FUNC(int) PyDict_ClearWatcher(int watcher_id);
 // Mark given dictionary as "watched" (callback will be called if it is modified)
 PyAPI_FUNC(int) PyDict_Watch(int watcher_id, PyObject* dict);
 PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);
+
+// Create a frozendict. Create an empty dictionary if iterable is NULL.
+PyAPI_FUNC(PyObject*) PyFrozenDict_New(PyObject *iterable);

Include/internal/pycore_dict.h

@@ -408,6 +408,15 @@ _Py_DECREF_BUILTINS(PyObject *op)
 }
 #endif
 
+/* frozendict */
+typedef struct {
+    PyDictObject ob_base;
+    Py_hash_t ma_hash;
+} PyFrozenDictObject;
+
+#define _PyFrozenDictObject_CAST(op) \
+    (assert(PyFrozenDict_Check(op)), _Py_CAST(PyFrozenDictObject*, (op)))
+
 #ifdef __cplusplus
 }
 #endif

Include/internal/pycore_typeobject.h

@@ -26,6 +26,7 @@ extern "C" {
 #define _Py_TYPE_VERSION_BYTEARRAY 9
 #define _Py_TYPE_VERSION_BYTES 10
 #define _Py_TYPE_VERSION_COMPLEX 11
+#define _Py_TYPE_VERSION_FROZENDICT 12
 
 #define _Py_TYPE_VERSION_NEXT 16
 

Lib/_collections_abc.py

@@ -823,6 +823,7 @@ def __eq__(self, other):
 
     __reversed__ = None
 
+Mapping.register(frozendict)
 Mapping.register(mappingproxy)
 Mapping.register(framelocalsproxy)