automap

automap is a Python package containing high-performance autoincremented integer-valued mappings.

To install, just run pip install automap.

Examples

automap objects are sort of like "inverse sequences". They come in two variants:

FrozenAutoMap

>>> from automap import FrozenAutoMap

FrozenAutoMap objects are immutable. They can be constructed from any iterable of hashable, unique keys.

>>> a = FrozenAutoMap("AAA")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: 'A'
>>> a = FrozenAutoMap("ABC")
>>> a
automap.FrozenAutoMap(['A', 'B', 'C'])

The values are integers, incrementing according to the order of the original keys:

>>> a["A"]
0
>>> a["C"]
2
>>> a["X"]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 'X'

The full Mapping interface is provided:

>>> [*a.keys()]
['A', 'B', 'C']
>>> [*a.values()]
[0, 1, 2]
>>> [*a.items()]
[('A', 0), ('B', 1), ('C', 2)]
>>> a.get("X", 42)
42
>>> "B" in a
True
>>> [*a]
['A', 'B', 'C']

They may also be combined with each other using the | operator:

>>> b = FrozenAutoMap(range(5))
>>> c = FrozenAutoMap(range(5, 10))
>>> b | c
automap.FrozenAutoMap([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> b |= c  # Note that b is reassigned, not mutated!
>>> b
automap.FrozenAutoMap([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

AutoMap

>>> from automap import AutoMap

Unlike FrozenAutoMap objects, AutoMap objects can grow; new keys may be added, but existing ones may not be deleted or changed.

>>> d = AutoMap("ABC")
>>> d
automap.AutoMap(['A', 'B', 'C'])
>>> d |= "DEF"  # Here, d *is* mutated!
>>> d
automap.AutoMap(['A', 'B', 'C', 'D', 'E', 'F'])

They also have add and update methods for adding new keys:

>>> e = AutoMap(["I", "II", "III"])
>>> e.add("IV")
>>> e
automap.AutoMap(['I', 'II', 'III', 'IV'])
>>> e.update(["V", "VI", "VII"])
>>> e
automap.AutoMap(['I', 'II', 'III', 'IV', 'V', 'VI', 'VII'])

Performance

Tests show string-keyed AutoMap objects being created 70% faster and accessed 5% faster than the equivalent dict construction, on average. They also tend to take up the same amount of memory. You can run invoke performance from this repository to see the comparison on your machine.

More details on the design can be found in automap.c.