With the release of Python 3.15 Alpha 6, PEP 814 has officially landed, introducing the much-anticipated `frozendict` to the built-in namespace. This provide...
What frozendict adds to the language
With Python 3.15 Alpha 6, PEP 814 lands frozendict in the built-in namespace as a first-class immutable mapping. Like a regular dict, it stores key-value pairs with hash-based lookup. Unlike a regular dict, once constructed it cannot be mutated: no item assignment, no update, no pop, no clear. That single constraint is the point. You get a mapping that is safe to share across call boundaries, store as an attribute, or use where the contract is “this configuration does not change under you.”
Because the object is immutable and its keys and values must themselves be hashable in the usual way when the whole mapping is used as a key or set member, a frozendict can participate in places a plain dict cannot. That closes a long-standing gap between frozenset for collections of unique items and the absence of a standard frozen map for structured key-value data.
When immutable mappings beat plain dicts
Mutable dicts remain the default for most application code. You reach for frozendict when mutation would be a bug rather than a feature. Typical cases include default options passed into a library function, snapshot-style records returned from a parser, cache keys built from structured parameters, and constants that should never grow accidental runtime fields.
- Share a mapping across threads or async tasks without locks on the map itself (values must still be used carefully if they are mutable).
- Use the mapping as a dict key or set element when the full key space is defined by several fields at once.
- Document intent: callers see “read-only map” in the type and API surface, not “please do not modify this dict.”
- Compose safely: nested structures can mix frozendict with frozenset and other hashable types when you need deep immutability by construction.
If you still need occasional updates, the pattern is rebuild, not mutate: construct a new frozendict from the old one plus the changed pairs. That cost is acceptable for configuration and identity keys; it is the wrong tool for high-churn working sets where a normal dict is clearer and faster to edit in place.
Construction, hashing, and equality
You build a frozendict much like a dict—from pairs, from a mapping, or with keyword-style construction depending on the accepted constructors in the spec—then treat the result as fixed. Equality should compare content the same way mappings usually do: same keys, same values, order-independent. Hashability follows from immutability plus hashable contents, so two frozendicts that compare equal must hash equal, which is what makes them reliable in sets and as keys.
Watch the contents. A frozendict that holds a mutable value (for example a list) is still “frozen” at the map layer, but the nested object can change, which breaks the mental model of a stable snapshot and can invalidate hash-based containers if you were careless enough to put such a value inside a key. Prefer hashable, immutable values when the frozendict itself will be hashed.
Practical migration and API design
For library authors, accepting Mapping (read-only protocol) and returning frozendict when you own the data is a clean split: callers may pass any mapping, and you publish a value they cannot accidentally rewrite. For application code, convert at the boundary—after loading config, after validating input—then pass the frozen form inward so internal layers never need to defensively copy.
Keep ordinary dicts for builders, accumulators, and anything that grows field by field. Reach for frozendict when the data has become a finished value: a policy object, a feature flag set, a structured cache key, or a public constant. PEP 814’s addition to the built-in namespace means that choice no longer depends on third-party packages or ad hoc namedtuple workarounds. Use it where immutability is the contract; leave mutation where mutation is the workflow.