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

Add TYPE_FROZENDICT to the marshal module.

Add C API functions:

* PyAnyDict_Check()
* PyAnyDict_CheckExact()
* PyFrozenDict_Check()
* PyFrozenDict_CheckExact()
* PyFrozenDict_New()

Add PyFrozenDict_Type C type.

Author: vstinner

Doc/c-api/dict.rst

@@ -490,6 +490,46 @@ Dictionary View Objects
    always succeeds.
 
 
+Frozen Dictionary Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: next
+
+
+.. 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.
+
+
 Ordered Dictionaries
 ^^^^^^^^^^^^^^^^^^^^
 

Doc/library/stdtypes.rst

@@ -5305,8 +5305,8 @@ frozenset, a temporary one is created from *elem*.
 
 .. _typesmapping:
 
-Mapping Types --- :class:`dict`
-===============================
+Mapping Types --- :class:`dict`, :class:`frozendict`
+====================================================
 
 .. index::
    pair: object; mapping
@@ -5317,8 +5317,9 @@ Mapping Types --- :class:`dict`
    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.)
 
@@ -5587,6 +5588,15 @@ can be used interchangeably to index the same dictionary entry.
    .. versionchanged:: 3.8
       Dictionaries are now reversible.
 
+.. 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.
+
+   .. versionadded:: next
+
 
 .. seealso::
    :class:`types.MappingProxyType` can be used to create a read-only view
@@ -6062,6 +6072,7 @@ list is non-exhaustive.
 * :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)
 

Lib/test/mapping_tests.py

@@ -4,7 +4,7 @@
 from test import support
 
 
-class BasicTestMappingProtocol(unittest.TestCase):
+class BasicTestImmutableMappingProtocol(unittest.TestCase):
     # This base class can be used to check that an object conforms to the
     # mapping protocol
 
@@ -22,10 +22,7 @@ def _empty_mapping(self):
     def _full_mapping(self, data):
         """Return a mapping object with the value contained in data
         dictionary"""
-        x = self._empty_mapping()
-        for key, value in data.items():
-            x[key] = value
-        return x
+        return self.type2test(data)
 
     def __init__(self, *args, **kw):
         unittest.TestCase.__init__(self, *args, **kw)
@@ -88,6 +85,72 @@ def check_iterandlist(iter, lst, ref):
         self.assertEqual(d.get(knownkey, knownvalue), knownvalue)
         self.assertNotIn(knownkey, d)
 
+    def test_constructor(self):
+        self.assertEqual(self._empty_mapping(), self._empty_mapping())
+
+    def test_bool(self):
+        self.assertTrue(not self._empty_mapping())
+        self.assertTrue(self.reference)
+        self.assertTrue(bool(self._empty_mapping()) is False)
+        self.assertTrue(bool(self.reference) is True)
+
+    def test_keys(self):
+        d = self._empty_mapping()
+        self.assertEqual(list(d.keys()), [])
+        d = self.reference
+        self.assertIn(list(self.inmapping.keys())[0], d.keys())
+        self.assertNotIn(list(self.other.keys())[0], d.keys())
+        self.assertRaises(TypeError, d.keys, None)
+
+    def test_values(self):
+        d = self._empty_mapping()
+        self.assertEqual(list(d.values()), [])
+
+        self.assertRaises(TypeError, d.values, None)
+
+    def test_items(self):
+        d = self._empty_mapping()
+        self.assertEqual(list(d.items()), [])
+
+        self.assertRaises(TypeError, d.items, None)
+
+    def test_len(self):
+        d = self._empty_mapping()
+        self.assertEqual(len(d), 0)
+
+    def test_getitem(self):
+        d = self.reference
+        self.assertEqual(d[list(self.inmapping.keys())[0]],
+                         list(self.inmapping.values())[0])
+
+        self.assertRaises(TypeError, d.__getitem__)
+
+    # no test_fromkeys or test_copy as both os.environ and selves don't support it
+
+    def test_get(self):
+        d = self._empty_mapping()
+        self.assertTrue(d.get(list(self.other.keys())[0]) is None)
+        self.assertEqual(d.get(list(self.other.keys())[0], 3), 3)
+        d = self.reference
+        self.assertTrue(d.get(list(self.other.keys())[0]) is None)
+        self.assertEqual(d.get(list(self.other.keys())[0], 3), 3)
+        self.assertEqual(d.get(list(self.inmapping.keys())[0]),
+                         list(self.inmapping.values())[0])
+        self.assertEqual(d.get(list(self.inmapping.keys())[0], 3),
+                         list(self.inmapping.values())[0])
+        self.assertRaises(TypeError, d.get)
+        self.assertRaises(TypeError, d.get, None, None, None)
+
+
+class BasicTestMappingProtocol(BasicTestImmutableMappingProtocol):
+    def _full_mapping(self, data):
+        """Return a mapping object with the value contained in data
+        dictionary"""
+        x = self._empty_mapping()
+        for key, value in data.items():
+            x[key] = value
+        return x
+
     def test_write(self):
         # Test for write operations on mapping
         p = self._empty_mapping()
@@ -130,46 +193,6 @@ def test_write(self):
         p=self._empty_mapping()
         self.assertRaises(KeyError, p.popitem)
 
-    def test_constructor(self):
-        self.assertEqual(self._empty_mapping(), self._empty_mapping())
-
-    def test_bool(self):
-        self.assertTrue(not self._empty_mapping())
-        self.assertTrue(self.reference)
-        self.assertTrue(bool(self._empty_mapping()) is False)
-        self.assertTrue(bool(self.reference) is True)
-
-    def test_keys(self):
-        d = self._empty_mapping()
-        self.assertEqual(list(d.keys()), [])
-        d = self.reference
-        self.assertIn(list(self.inmapping.keys())[0], d.keys())
-        self.assertNotIn(list(self.other.keys())[0], d.keys())
-        self.assertRaises(TypeError, d.keys, None)
-
-    def test_values(self):
-        d = self._empty_mapping()
-        self.assertEqual(list(d.values()), [])
-
-        self.assertRaises(TypeError, d.values, None)
-
-    def test_items(self):
-        d = self._empty_mapping()
-        self.assertEqual(list(d.items()), [])
-
-        self.assertRaises(TypeError, d.items, None)
-
-    def test_len(self):
-        d = self._empty_mapping()
-        self.assertEqual(len(d), 0)
-
-    def test_getitem(self):
-        d = self.reference
-        self.assertEqual(d[list(self.inmapping.keys())[0]],
-                         list(self.inmapping.values())[0])
-
-        self.assertRaises(TypeError, d.__getitem__)
-
     def test_update(self):
         # mapping argument
         d = self._empty_mapping()
@@ -265,22 +288,6 @@ def __next__(self):
 
         self.assertRaises(ValueError, d.update, [(1, 2, 3)])
 
-    # no test_fromkeys or test_copy as both os.environ and selves don't support it
-
-    def test_get(self):
-        d = self._empty_mapping()
-        self.assertTrue(d.get(list(self.other.keys())[0]) is None)
-        self.assertEqual(d.get(list(self.other.keys())[0], 3), 3)
-        d = self.reference
-        self.assertTrue(d.get(list(self.other.keys())[0]) is None)
-        self.assertEqual(d.get(list(self.other.keys())[0], 3), 3)
-        self.assertEqual(d.get(list(self.inmapping.keys())[0]),
-                         list(self.inmapping.values())[0])
-        self.assertEqual(d.get(list(self.inmapping.keys())[0], 3),
-                         list(self.inmapping.values())[0])
-        self.assertRaises(TypeError, d.get)
-        self.assertRaises(TypeError, d.get, None, None, None)
-
     def test_setdefault(self):
         d = self._empty_mapping()
         self.assertRaises(TypeError, d.setdefault)