[WIP] PEP 814: Add built-in frozendict type

* Basic tests
* Bare minimum documentation
* Support frozendict in marshal, pickle, json
* Replace dict with frozendict in many stdlib modules

Co-Authored-by: Donghee Na <donghee.na@python.org>
Co-Authored-by: Marco Sulla <github@marco.sulla.e4ward.com>

Author: 3 people

Doc/library/stdtypes.rst

@@ -4914,8 +4914,8 @@ The constructors for both classes work the same:
 
 .. _typesmapping:
 
-Mapping Types --- :class:`dict`
-===============================
+Mapping Types --- :class:`dict`, :class:`frozendict`
+====================================================
 
 .. index::
    pair: object; mapping
@@ -4926,8 +4926,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
+Mappings are mutable objects.  There is 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.)
 
@@ -5199,6 +5200,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
@@ -5532,6 +5542,7 @@ list is non-exhaustive.
 * :class:`list`
 * :class:`dict`
 * :class:`set`
+* :class:`frozendict`
 * :class:`frozenset`
 * :class:`type`
 * :class:`asyncio.Future`

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
@@ -52,7 +62,7 @@ PyAPI_FUNC(int) PyDict_SetDefaultRef(PyObject *mp, PyObject *key, PyObject *defa
 /* 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);
@@ -103,3 +113,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

@@ -406,6 +406,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_object.h

@@ -863,8 +863,7 @@ static inline Py_hash_t
 _PyObject_HashFast(PyObject *op)
 {
     if (PyUnicode_CheckExact(op)) {
-        Py_hash_t hash = FT_ATOMIC_LOAD_SSIZE_RELAXED(
-                             _PyASCIIObject_CAST(op)->hash);
+        Py_hash_t hash = PyUnstable_Unicode_GET_CACHED_HASH(op);
         if (hash != -1) {
             return hash;
         }

Lib/_collections_abc.py

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

Lib/_compat_pickle.py

@@ -183,6 +183,7 @@
     'StringIO':  'io',
     'cStringIO': 'io',
 })
+IMPORT_MAPPING = frozendict(IMPORT_MAPPING)
 
 REVERSE_IMPORT_MAPPING.update({
     '_bz2': 'bz2',
@@ -198,6 +199,7 @@
     ('UserDict', 'UserDict'): ('collections', 'UserDict'),
     ('socket', '_socketobject'): ('socket', 'SocketType'),
 })
+NAME_MAPPING = frozendict(NAME_MAPPING)
 
 REVERSE_NAME_MAPPING.update({
     ('_functools', 'reduce'): ('__builtin__', 'reduce'),