{"library":"immutabledict","title":"Immutable Dictionary","description":"immutabledict is a Python library providing an immutable wrapper around dictionaries. It functions as a drop-in replacement for standard dictionaries where immutability is desired, implementing the complete mapping interface. Forked from `frozendict`, `immutabledict` offers an MIT-licensed alternative to the LGPL-3.0 licensed original. It also includes `ImmutableOrderedDict` for order-preserving immutable mappings. The library is actively maintained with frequent minor and patch releases.","status":"active","version":"4.3.1","language":"en","source_language":"en","source_url":"https://github.com/corenting/immutabledict","tags":["immutable","dictionary","frozendict","mapping","data-structure"],"install":[{"cmd":"pip install immutabledict","lang":"bash","label":"Install immutabledict"}],"dependencies":[],"imports":[{"symbol":"immutabledict","correct":"from immutabledict import immutabledict"},{"note":"For an order-preserving immutable dictionary.","symbol":"ImmutableOrderedDict","correct":"from immutabledict import ImmutableOrderedDict"}],"quickstart":{"code":"from immutabledict import immutabledict\n\n# Create an immutable dictionary\nmy_item = immutabledict({\"a\": \"value\", \"b\": \"other_value\"})\n\nprint(f\"Value for 'a': {my_item['a']}\")\n\n# Attempting to modify an immutabledict will raise a TypeError\ntry:\n    my_item[\"c\"] = \"new_value\"\nexcept TypeError as e:\n    print(f\"Attempted modification failed: {e}\")\n\n# You can create a new immutabledict with changes using dictionary union operator (PEP 584)\nnew_item = my_item | {\"c\": \"another_value\"}\nprint(f\"New item (original unchanged): {new_item}\")\nprint(f\"Original item: {my_item}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later"},{"fix":"Upgrade your Python environment to version 3.8 or newer.","message":"Support for Python 3.7 was officially dropped.","severity":"breaking","affected_versions":"3.0.0 and later"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"4.0.0 and later"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}