Frozendict

Common errors

• TypeError: 'frozendict' object does not support item assignment

  cause 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

  cause 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.

  cause 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'

  cause 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.

Warnings

• breaking The `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.
• gotcha Frozendict 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)`.
• gotcha The 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.
• gotcha Prior 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.

Install

• pip install frozendict Install frozendict

Imports

• frozendict

  from frozendict import frozendict

• deepfreeze

  from frozendict import deepfreeze

  Introduced in v2.4.0 for recursively freezing objects.

Quickstart

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}")