frozendict

library2.4.7pypypi✓ verified 52d ago

Frozendict is a Python library that provides a simple immutable dictionary implementation, mimicking Python's built-in `dict` but with unchangeable contents after creation. It offers hashability, allowing frozendict instances to be used as keys in other dictionaries or elements in sets. The library is actively maintained, with version 2.4.7 being the latest, and sees regular releases with performance improvements, new features like `deepfreeze`, and support for various architectures.

serialization data

pip install frozendict

github ↗package ↗

Install & Compatibility

Where this runs

tested against v2.4.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.010s · 18.1MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.6s · import 0.010s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

frozendict

✓ from frozendict import frozendict

deepfreeze

✓ from frozendict import deepfreeze

Introduced in v2.4.0 for recursively freezing objects.

Demonstrates creating a frozendict, accessing elements, its immutability and hashability, and the use of `deepfreeze` for recursive immutability.

from frozendict import frozendict, deepfreeze # Create an immutable dictionary fd = frozendict({'a': 1, 'b': 2, 'c': [3, 4]}) print(f"Initial frozendict: {fd}") # Access elements like a regular dict print(f"Value for 'a': {fd['a']}") # Attempting to modify raises an error try: fd['d'] = 5 except TypeError as e: print(f"Caught expected error on modification attempt: {e}") # Note that nested mutable objects are still mutable unless deepfrozen fd['c'].append(5) print(f"Frozendict after modifying nested list: {fd}") # Frozendict instances are hashable, so they can be dict keys hash_map = {fd: 'this is a key'} print(f"Using frozendict as a key: {hash_map[fd]}") # Use deepfreeze for full immutability of nested structures mutable_data = {'x': 10, 'y': [11, 12], 'z': {'key': 'value'}} deep_frozen_data = deepfreeze(mutable_data) print(f"Deep frozen data: {deep_frozen_data}") try: deep_frozen_data['y'].append(13) # This will now raise an error except TypeError as e: print(f"Caught expected error on deepfrozen nested modification: {e}")

Debug

Known issues

breakingThe `deepfreeze` function (introduced in v2.4.0) no longer modifies the original object in place. It now returns a new frozen object.

fix

If you relied on `deepfreeze` modifying the original object, you must now explicitly assign the result. For example, change `deepfreeze(my_obj)` to `my_obj = deepfreeze(my_obj)` or assign to a new variable.

affects: >=2.4.2

gotchaFrozendict instances are only shallowly immutable. If a frozendict contains mutable nested objects (e.g., lists or dictionaries), these nested objects can be modified in place. Furthermore, if a frozendict contains any unhashable mutable nested objects, the frozendict itself will become unhashable, preventing its use as a dictionary key or in sets.

fix

To ensure deep immutability and hashability when using frozendict with potentially mutable nested data, apply `deepfreeze` to the data before creating the frozendict, or to the frozendict instance after creation. For example, `my_fd = frozendict(deepfreeze(my_dict))` or `my_hashable_fd = deepfreeze(my_fd)`.

affects: >=2.4.6

gotchaThe library typically uses a C extension for performance. In environments where C extensions are problematic or if you need to force the pure Python implementation for debugging, you can set an environment variable.

fix

Set the environment variable `FROZENDICT_PURE_PY=1` before running your Python script to force the pure Python implementation. This might lead to different performance characteristics.

affects: >=2.3.9

gotchaPrior to version 2.4.7, pickling operations for the C extension could be significantly slower than the pure Python implementation or standard dicts. This was addressed with performance improvements in the latest release.

fix

Upgrade to frozendict v2.4.7 or later to benefit from improved pickling performance when using the C extension.

affects: <2.4.7

Errors

Common errors & fixes

TypeError: 'frozendict' object does not support item assignment

You are attempting to modify a `frozendict` instance after its creation by assigning a new value to a key, which is not allowed because `frozendict` objects are immutable.

fix

Instead of modifying an existing `frozendict`, create a new `frozendict` using the `set()` method or the union operator (`|`) to include the desired changes.

TypeError: 'frozendict' object doesn't support item deletion

You are attempting to delete an item from a `frozendict` instance using `del`, which is not permitted as `frozendict` is immutable.

fix

To remove an item, create a new `frozendict` using the `delete()` method, which returns a new instance without the specified key.

TypeError: Not all values are hashable.

This error occurs when you try to calculate the hash of a `frozendict` (e.g., to use it as a key in another dictionary or as an element in a set) but one or more of its *values* are mutable and thus unhashable (e.g., lists, sets, or other mutable dictionaries). Keys must always be hashable.

fix

Ensure that all values within the `frozendict` are themselves immutable and hashable (e.g., numbers, strings, tuples, `frozenset`, or other `frozendict` instances). If you need mutable nested structures, the `frozendict` itself cannot be hashed.

KeyError: 'some_key'

You are trying to access a key in the `frozendict` that does not exist. This behavior is consistent with Python's built-in `dict` type.

fix

Before accessing an item, check if the key exists using `in` operator, or use the `.get(key, default_value)` method to provide a fallback value if the key is not found.

Upgrade

Version history

2.4.7latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

seranking-bot

ahrefsbot