Repository files navigation

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 thecontextvarsmodule (seePEP 550 andPEP 567 for more details).

Immutable mappings based on HAMT have O(log N) performance for bothset() andget() operations, which is essentially O(1) forrelatively small mappings.

Below is a visualization of a simple get/set benchmark comparingHAMT to an immutable mapping implemented with a Python dictcopy-on-write approach (the benchmark code is availablehere):

immutables requires Python 3.6+ and is available on PyPI:

$ pip install immutables

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

TheMap object implements thecollections.abc.Mapping ABCso working with it is very similar to working with Python dicts:

importimmutablesmap=immutables.Map(a=1,b=2)print(map['a'])# will print '1'print(map.get('z',100))# will print '100'print('z'inmap)# will print 'False'

Since Maps are immutable, there is a special API for mutations thatallow 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']=100delmap_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 examplerewritten in a more idiomatic way:

withmap.mutate()asmm:mm['a']=100delmm['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'})>

• An immutable version of Pythonset type with efficientadd() anddiscard() operations.

Apache 2.0