Construction

frozendict implements a dict-like construction API:

• frozendict() creates a new empty immutable mapping.
• frozendict(**kwargs) creates a mapping from **kwargs, e.g. frozendict(x=1, y=2).
• frozendict(collection) creates a mapping from the passed collection object. The passed collection object can be:
  • a dict,
  • another frozendict,
  • or an iterable of key/value tuples.
• frozendict(collection, **kwargs) combines the two previous constructions.

Keys must be hashable, but values can be non-hashable. Using hashable values creates a hashable frozendict.

Creating a frozendict from a dict, frozendict(dict), has a complexity of O(n): items are copied (shallow copy).

The insertion order is preserved.

Iteration

As frozendict implements the standard collections.abc.Mapping protocol, so all expected methods of iteration are supported:

assert list(m.items()) == [('foo', 'bar')]
assert list(m.keys()) == ['foo']
assert list(m.values()) == ['bar']
assert list(m) == ['foo']

Iterating on frozendict, as on dict, uses the insertion order.

Hashing and Comparison

frozendict instances can be hashable just like tuple objects:

hash(frozendict(foo='bar'))  # works
hash(frozendict(foo=['a', 'b', 'c']))  # error, list is not hashable

The hash value does not depend on the items’ order. It is computed on keys and values. Pseudo-code of hash(frozendict):

hash(frozenset(frozendict.items()))

Equality test does not depend on the items’ order either. Example:

>>> a = frozendict(x=1, y=2)
>>> b = frozendict(y=2, x=1)
>>> hash(a) == hash(b)
True
>>> a == b
True

It’s possible to compare frozendict to dict. Example:

>>> frozendict(x=1, y=2) == dict(x=1, y=2)
True

Union operators

It’s possible to join two frozendict, or a frozendict with a dict, with the merge (|) operator. Example:

>>> frozendict(x=1) | frozendict(y=1)
frozendict({'x': 1, 'y': 1})
>>> frozendict(x=1) | dict(y=1)
frozendict({'x': 1, 'y': 1})

If some keys are in common, the values of the right operand are taken:

>>> frozendict(x=1, y=2) | frozendict(y=5)
frozendict({'x': 1, 'y': 5})

The update operator |= does not modify a frozendict in-place, but creates a new frozendict:

>>> d = frozendict(x=1)
>>> copy = d
>>> d |= frozendict(y=2)
>>> d
frozendict({'x': 1, 'y': 2})
>>> copy   # left unchanged
frozendict({'x': 1})

See also PEP 584 “Add Union Operators To dict”.

Copy

frozendict.copy() returns a shallow copy. In CPython, it simply returns the same frozendict (new reference).

Use copy.deepcopy() to get a deep copy.

Example:

>>> import copy
>>> d = frozendict(mutable=[])
>>> shallow_copy = d.copy()
>>> deep_copy = copy.deepcopy(d)
>>> d['mutable'].append('modified')
>>> d
frozendict({'mutable': ['modified']})
>>> shallow_copy  # modified!
frozendict({'mutable': ['modified']})
>>> deep_copy     # unchanged
frozendict({'mutable': []})

Typing

It is possible to use the standard typing notation for frozendicts:

m: frozendict[str, int] = frozendict(x=1)

Representation

frozendict will not use a special syntax for its representation. The repr() of a frozendict instance looks like this:

>>> frozendict(x=1, y=2)
frozendict({'x': 1, 'y': 2})

C API

Add the following APIs:

• PyAnyDict_Check(op) macro
• PyAnyDict_CheckExact(op) macro
• PyFrozenDict_Check() macro
• PyFrozenDict_CheckExact() macro
• PyFrozenDict_New(collection) function
• PyFrozenDict_Type

Even if frozendict is not a dict subclass, it can be used with PyDict_GetItemRef() and similar “PyDict_Get” functions.

Passing a frozendict to PyDict_SetItem() or PyDict_DelItem() fails with TypeError. PyDict_Check() on a frozendict is false.

Python modules

Replace dict with frozendict in function results:

• email.headerregistry: ParameterizedMIMEHeader.params() (replace MappingProxyType)
• enum: EnumType.__members__() (replace MappingProxyType)

Replace dict with frozendict for constants:

• _opcode_metadata: _specializations, _specialized_opmap, opmap
• _pydatetime: specs (in _format_time())
• _pydecimal: _condition_map
• bdb: _MonitoringTracer.EVENT_CALLBACK_MAP
• dataclasses: _hash_action
• dis: deoptmap, COMPILER_FLAG_NAMES
• functools: _convert
• gettext: _binary_ops, _c2py_ops
• imaplib: Commands, Mon2num
• json.decoder: _CONSTANTS, BACKSLASH
• json.encoder: ESCAPE_DCT
• json.tool: _group_to_theme_color
• locale: locale_encoding_alias, locale_alias, windows_locale
• opcode: _cache_format, _inline_cache_entries
• optparse: _builtin_cvt
• platform: _ver_stages, _default_architecture
• plistlib: _BINARY_FORMAT
• ssl: _PROTOCOL_NAMES
• stringprep: b3_exceptions
• symtable: _scopes_value_to_name
• tarfile: PAX_NUMBER_FIELDS, _NAMED_FILTERS
• token: tok_name, EXACT_TOKEN_TYPES
• tomllib._parser: BASIC_STR_ESCAPE_REPLACEMENTS
• typing: _PROTO_ALLOWLIST

Accept frozendict type:

• builtins: eval() and exec() (globals argument)

Extension modules

Replace dict with frozendict for constants:

• errno: errorcode

Inherit from dict

If frozendict inherits from dict, it would become possible to call dict methods to mutate an immutable frozendict. For example, it would be possible to call dict.__setitem__(frozendict, key, value).

It may be possible to prevent modifying frozendict using dict methods, but that would require to explicitly exclude frozendict which can affect dict performance. Also, there is a higher risk of forgetting to exclude frozendict in some methods.

If frozendict does not inherit from dict, there is no such issue.

New syntax for frozendict literals

Various syntaxes have been proposed to write frozendict literals.

A new syntax can be added later if needed.

Method to convert dict to frozendict

Different methods have been proposed to convert a mutable dict to an immutable frozendict with O(1) complexity, such as dict.freeze(). The idea would be to move dict contents into frozendict: it would make the dict empty. Another idea would be to use “copy-on-write”: only copy the dict at its first modification.

We consider that such method can be added later if needed, but it doesn’t have to be added right now. Moreover, if such method is added, it would be nice to add a similar method for list/tuple and set/frozenset. See also PEP 351 (Freeze protocol).

Type annotation

It has been proposed to add class TD(TypedDict, frozen=True) or Frozen[MyTypedDict] to define a frozendict type.

We consider that such type can be added later if needed.