immutables

library0.21pypypi✓ verified 30d ago

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.

data serialization

pip install immutables

github ↗package ↗

INSTALL

IMPORT

SIG · IMMUTABLES

immutables

datapythonv0.21

Install

1.6s avg

Import

12ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.21 · 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.95 runs

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

glibc

py 3.10–3.95 runs

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

16MB installed

● package 16MB

Code

Verified usage

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

Map

✓ import immutables my_map = immutables.Map()

✗ from immutables import Map # Not strictly wrong, but the common pattern is 'import immutables'

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.

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.

import immutables # Create an immutable map my_map = immutables.Map({"a": 1, "b": 2}) print(f"Original Map: {my_map}") # Set a value (returns a *new* map) new_map = my_map.set("c", 3) print(f"Map after setting 'c': {new_map}") print(f"Original map is unchanged: {my_map}") # Delete a value (returns a *new* map) map_after_delete = new_map.delete("b") print(f"Map after deleting 'b': {map_after_delete}") # Batch mutations using a context manager for efficiency with my_map.mutate() as mutable_map: mutable_map["d"] = 4 del mutable_map["a"] mutable_map["e"] = 5 batch_mutated_map = mutable_map.finish() print(f"Map after batch mutations: {batch_mutated_map}")

Debug

Known issues

gotchaThis `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.

fix

Ensure you understand the specific purpose of `immutables.Map` for immutable dictionary-like structures in Python, rather than general immutable data classes.

affects: All versions

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

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.

affects: All versions

gotchaWhile 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)).

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.

affects: All versions

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

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'immutable'

The `immutables` library is often mistakenly imported with the singular name 'immutable', leading to a ModuleNotFoundError.

fix

Ensure the correct library name, 'immutables', is used in the import statement and that the library is installed (`pip install immutables`).

KeyError: 'some_key'

Attempting to access a key in an `immutables.Map` that does not exist will raise a KeyError, similar to a standard Python dictionary.

fix

Before accessing a key, check if it exists using `in` or `get()` with a default value. For example: `my_map.get('some_key', default_value)` or `if 'some_key' in my_map: value = my_map['some_key']`.

TypeError: unhashable type: 'list'

Keys in `immutables.Map` (like standard Python dictionaries) must be hashable. Mutable types like lists or dictionaries cannot be used as keys, leading to a TypeError.

fix

Use immutable types as keys, such as strings, numbers, or tuples. If you need to use a collection as a key, convert it to an immutable type like a tuple: `immutables.Map({(1, 2): 'value'})`.

Upgrade

Version history

0.21latest on PyPI · released Oct 10, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/MagicStack/immutables ↗

packagehttps://pypi.org/project/immutables/ ↗