Only very rarely does Python add a new standard data type. Python 3.15, when it’s released later this year, will come with one—an immutable dictionary, frozendict.

Dictionaries in Python correspond to hashmaps in Java. They are a way to associate keys with values. The Python dict, as it’s called, is tremendously powerful and versatile. In fact, the dict structure is used by the CPython interpreter to handle many things internally.

But a dict has a big limitation: it’s not hashable. A hashable type in Python has a hash value that never changes during its lifetime. Strings, numerical values (integers and floats), and tuples are all hashable because they are immutable. Container types, like lists, sets, and, yes, dicts, are mutable, so can’t guarantee they hold the same values over time.

Python has long included a frozenset type—a version of a set that doesn’t change over its lifetime and is hashable. Because sets are basically dictionaries with keys and no values, why not also have a frozendict type? Well, after much debate, we finally got just that. If you download Python 3.15 alpha 7 or later, you’ll be able to try it out.

The basics of a frozendict

In many respects, a frozendict behaves exactly like a regular dictionary. The main difference is you can’t use the conventional dictionary constructor (the {} syntax) to make one. You must use the frozendict() constructor:

my_frozendict = frozendict(
    x = 1, y = True, z = "Hello"
)

You can also take an existing dictionary and give it to the constructor:

my_frozendict = frozendict(
    {x:1, y:True, z:"Hello", "A string":"Another string"}
)

One big advantage of using a dict as the source is that you have more control over what the keys can be. In the above example, we can’t use "A string" as a key in the first constructor, because that’s not a valid argument name. But we can use any string we like as a dict key.

The new frozendict bears some resemblance to an existing type in the collections module, collections.frozenmap. But frozendict differs in several key ways:

• frozendict is built-in, so doesn’t need to be imported from a module.
• frozenmap does not preserve insertion order.
• Lookups for keys in a frozenmap are potentially slower (O(log n) than in a frozendict (O(1)).

Working with frozendicts

A frozendict behaves exactly like a regular dict as long as all you’re doing is reading values from it.

For instance, if you want to get a value using a key, it’s the same: use the syntax the_frozendict[the_key]. If you want to iterate through a frozendict, that works the same way as with a regular dict: for key in the_frozendict:. Likewise for key/value pairs: for key, value in the_frozendict.items(): will work as expected.

Another convenient aspect of a frozendict is that they preserve insertion order. This feature was added relatively recently to dictionaries, and can be used to do things like create FIFO queues there. That the frozendict preserves the same behavior is very useful; it means you can iterate through a frozendict created from a regular dictionary and get the same items in the same sequence.

What frozendicts don’t let you do

The one big thing you can’t do with a frozendict is change its contents in any way. You can’t add keys, reassign their values, or remove keys. That means all of the following code would be invalid:

# new key x
my_frozendict[x]=y
# existing key q
my_frozendict[q]=p
# removing item
my_frozendict.pop()

Each of these would raise an exception. In the case of myfrozendict.pop(), note that the method .pop() doesn’t even exist on a frozendict.

While you can use merge and update operators on a frozendict, the way they work is a little deceptive. They don’t actually change anything; instead, they create a new frozendict object that contains the results of the merge or update. It’s similar to how “changing” a string or tuple really just means constructing a new instance of those types with the changes you want.

# Merge operation
my_frozendict = frozendict(x=1)
my_other_frozendict = frozendict(y=1)
new_fz = my_frozendict | my_other_frozendict

# Update operation
new_fz |= frozendict(x=2)

Use cases for frozendicts

Since a frozendict can’t be changed, it obviously isn’t a substitute for a regular dictionary, and it isn’t meant to be. The frozendict will come in handy when you want to do things like:

• Store key/value data that is meant to be immutable. For instance, if you collect key/value data from command-line options, you could store them in a frozendict to signal that they should not be altered over the lifetime of the program.
• Use a dictionary in some circumstance where you need a hashable type. For instance, if you want to use a dictionary as a key in a dictionary, or as an element in a set, a frozendict fits the bill.

It might be tempting to think a frozendict will provide better performance than a regular dict, considering it’s read-only. It’s possible, but not guaranteed, that eventual improvements in Python will enable better performance with immutable types. However, right now, that’s far from being a reason to use them.