Immutable Dictionary

Warnings

• breaking The `copy()` method signature was changed to no longer accept keyword arguments, aligning its behavior with the standard `dict.copy()` method. Previously, `copy(key='value')` would add `key: 'value'` to the copied dictionary.
  Fix: Instead of `my_immutabledict.copy(key='value')`, use `my_immutabledict | {'key': 'value'}` for simple additions, or `immutabledict({**my_immutabledict, 'key': 'value'})` for more complex updates or Python versions older than 3.9 where the `|` operator is not available for dicts.
• breaking Support for Python 3.7 was officially dropped.
  Fix: Upgrade your Python environment to version 3.8 or newer.
• gotcha While `immutabledict` ensures the dictionary's structure (keys and their assigned values) is immutable, it does *not* recursively make the *values* themselves immutable. If you store mutable objects (e.g., lists, other dictionaries) as values, those objects can still be modified in place through their references.
  Fix: To achieve deep immutability, ensure that all values stored within an `immutabledict` are themselves immutable types (e.g., numbers, strings, tuples, or other `immutabledict` instances).
• gotcha Operations that appear to 'modify' an `immutabledict` (like `set()`, `delete()`, `discard()`, or using the `|` operator) actually return a *new* `immutabledict` instance with the changes, rather than modifying the original in-place. This can incur performance overhead due to repeated object creation and copying if used in tight loops or scenarios with very frequent updates.
  Fix: Consider the performance implications for high-frequency update patterns. For scenarios requiring frequent mutable operations before a final 'freeze', a standard `dict` might be more appropriate, converted to `immutabledict` only when immutability is needed for sharing or hashing.
• gotcha Starting from v4.0.0, the internal implementation of `immutabledict` switched from overriding `__init__` to overriding `__new__` for constructor calls. While this is primarily an internal refactoring, it's a significant change that could affect advanced use cases such as highly specialized subclassing or detailed introspection that relied on the previous `__init__` behavior.
  Fix: If you maintain custom subclasses that override `__init__` or `__new__`, review their implementation to ensure they correctly chain to `super().__new__` in the base `immutabledict` class for proper initialization.

Install

• pip install immutabledict Install immutabledict

Imports

• immutabledict

  from immutabledict import immutabledict

• ImmutableOrderedDict

  from immutabledict import ImmutableOrderedDict

  For an order-preserving immutable dictionary.

Quickstart

Demonstrates how to create an immutabledict and shows that direct modification attempts will result in a TypeError. It also illustrates how to create a new immutabledict based on an existing one with updates.

from immutabledict import immutabledict

# Create an immutable dictionary
my_item = immutabledict({"a": "value", "b": "other_value"})

print(f"Value for 'a': {my_item['a']}")

# Attempting to modify an immutabledict will raise a TypeError
try:
    my_item["c"] = "new_value"
except TypeError as e:
    print(f"Attempted modification failed: {e}")

# You can create a new immutabledict with changes using dictionary union operator (PEP 584)
new_item = my_item | {"c": "another_value"}
print(f"New item (original unchanged): {new_item}")
print(f"Original item: {my_item}")