{"id":2068,"library":"immutables","title":"Immutable Collections","description":"The `immutables` library for Python provides a high-performance immutable mapping type, `immutables.Map`, built on a Hash Array Mapped Trie (HAMT) data structure. It offers efficient (O(log N)) operations for setting and getting values, making it suitable for functional programming paradigms and scenarios where data integrity and thread safety are paramount. The current version is 0.21. It follows a release cadence driven by bug fixes and performance improvements.","status":"active","version":"0.21","language":"en","source_language":"en","source_url":"https://github.com/MagicStack/immutables","tags":["immutable","collections","mapping","HAMT","functional programming","data structures"],"install":[{"cmd":"pip install immutables","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The primary immutable mapping type is exposed as `immutables.Map`. While `from immutables import Map` works, `import immutables` is more commonly seen in examples and provides access to other potential future utilities.","wrong":"from immutables import Map # Not strictly wrong, but the common pattern is 'import immutables'","symbol":"Map","correct":"import immutables\nmy_map = immutables.Map()"}],"quickstart":{"code":"import immutables\n\n# Create an immutable map\nmy_map = immutables.Map({\"a\": 1, \"b\": 2})\nprint(f\"Original Map: {my_map}\")\n\n# Set a value (returns a *new* map)\nnew_map = my_map.set(\"c\", 3)\nprint(f\"Map after setting 'c': {new_map}\")\nprint(f\"Original map is unchanged: {my_map}\")\n\n# Delete a value (returns a *new* map)\nmap_after_delete = new_map.delete(\"b\")\nprint(f\"Map after deleting 'b': {map_after_delete}\")\n\n# Batch mutations using a context manager for efficiency\nwith my_map.mutate() as mutable_map:\n    mutable_map[\"d\"] = 4\n    del mutable_map[\"a\"]\n    mutable_map[\"e\"] = 5\nbatch_mutated_map = mutable_map.finish()\nprint(f\"Map after batch mutations: {batch_mutated_map}\")","lang":"python","description":"Demonstrates creating an `immutables.Map`, performing individual `set` and `delete` operations which return new map instances, and using the `mutate()` context manager for efficient batch updates."},"warnings":[{"fix":"Ensure you understand the specific purpose of `immutables.Map` for immutable dictionary-like structures in Python, rather than general immutable data classes.","message":"This `immutables` library provides an immutable *mapping type* (`immutables.Map`), not a decorator for creating immutable classes. There is a different Python library (`python-immutable`) and a popular Java library (also named `Immutables`) with similar names but different functionality.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the provided immutable methods: `new_map = old_map.set(key, value)` to add/update, `new_map = old_map.delete(key)` to remove, or the `with old_map.mutate() as mutable_map:` context manager for batch changes, all of which return a *new* `immutables.Map` instance.","message":"Direct mutation of `immutables.Map` instances is not supported and will raise errors. Operations like `my_map['key'] = value` or `del my_map['key']` directly on an `immutables.Map` object are invalid.","severity":"breaking","affected_versions":"All versions"},{"fix":"Profile your application with `immutables.Map` for critical sections. For very large, frequently accessed maps where absolute O(1) average time complexity is essential, Python's built-in `dict` or `frozenset` might be more suitable if immutability guarantees are less strict.","message":"While often performing like O(1) for practical purposes, operations like `set()` and `get()` on `immutables.Map` are theoretically O(log N) due to its Hash Array Mapped Trie (HAMT) data structure. This can be a consideration for extremely large maps or highly performance-sensitive loops compared to Python's built-in `dict` (average O(1)).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Utilize the `with my_map.mutate() as mutable_map:` context manager for batch updates. This approach allows modifications to an intermediate mutable view, committing all changes to a single new immutable `Map` instance at the end of the block, thus optimizing memory and performance.","message":"For multiple consecutive modifications to an `immutables.Map`, chaining `set()` or `delete()` calls can be inefficient as each operation creates a new intermediate `Map` object. This can lead to increased memory allocation and performance overhead.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}