Skip to main content

Immutable Collections

Project description

An immutable mapping type for Python.

The underlying datastructure is a Hash Array Mapped Trie (HAMT) used in Clojure, Scala, Haskell, and other functional languages. This implementation is used in CPython 3.7 in the contextvars module (see PEP 550 and PEP 567 for more details).

Immutable mappings based on HAMT have O(log N) performance for both set() and get() operations, which is essentially O(1) for relatively small mappings.

Below is a visualization of a simple get/set benchmark comparing HAMT to an immutable mapping implemented with a Python dict copy-on-write approach (the benchmark code is available here):



immutables requires Python 3.6+ and is available on PyPI:

$ pip install immutables


immutables.Map is an unordered immutable mapping. Map objects are hashable, comparable, and pickleable.

The Map object implements the ABC so working with it is very similar to working with Python dicts:

import immutables

map = immutables.Map(a=1, b=2)

# will print '1'

print(map.get('z', 100))
# will print '100'

print('z' in map)
# will print 'False'

Since Maps are immutable, there is a special API for mutations that allow apply changes to the Map object and create new (derived) Maps:

map2 = map.set('a', 10)
print(map, map2)
# will print:
#   <immutables.Map({'a': 1, 'b': 2})>
#   <immutables.Map({'a': 10, 'b': 2})>

map3 = map2.delete('b')
print(map, map2, map3)
# will print:
#   <immutables.Map({'a': 1, 'b': 2})>
#   <immutables.Map({'a': 10, 'b': 2})>
#   <immutables.Map({'a': 10})>

Maps also implement APIs for bulk updates: MapMutation objects:

map_mutation = map.mutate()
map_mutation['a'] = 100
del map_mutation['b']
map_mutation.set('y', 'y')

map2 = map_mutation.finish()

print(map, map2)
# will print:
#   <immutables.Map({'a': 1, 'b': 2})>
#   <immutables.Map({'a': 100, 'y': 'y'})>

MapMutation objects are context managers. Here’s the above example rewritten in a more idiomatic way:

with map.mutate() as mm:
    mm['a'] = 100
    del mm['b']
    mm.set('y', 'y')
    map2 = mm.finish()

print(map, map2)
# will print:
#   <immutables.Map({'a': 1, 'b': 2})>
#   <immutables.Map({'a': 100, 'y': 'y'})>

Further development

  • An immutable version of Python set type with efficient add() and discard() operations.


Apache 2.0

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

immutables-0.19.tar.gz (85.5 kB view hashes)

Uploaded source

Built Distributions

immutables-0.19-cp311-cp311-win_amd64.whl (58.7 kB view hashes)

Uploaded cp311

immutables-0.19-cp310-cp310-win_amd64.whl (58.7 kB view hashes)

Uploaded cp310

immutables-0.19-cp39-cp39-win_amd64.whl (58.8 kB view hashes)

Uploaded cp39

immutables-0.19-cp38-cp38-win_amd64.whl (58.8 kB view hashes)

Uploaded cp38

immutables-0.19-cp37-cp37m-win_amd64.whl (58.8 kB view hashes)

Uploaded cp37

immutables-0.19-cp36-cp36m-win_amd64.whl (58.8 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page