Skip to main content

High-performance autoincremented integer-valued mappings.

Project description


latest versionlatest release datebuild statusissues

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

To install, just run pip install automap.


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


>>> 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"]
>>> a["C"]
>>> 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)
>>> "B" in a
>>> [*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])


>>> 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'])


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.

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

automap-0.6.2.tar.gz (11.0 kB view hashes)

Uploaded source

Built Distributions

automap-0.6.2-cp311-cp311-win_amd64.whl (12.4 kB view hashes)

Uploaded cp311

automap-0.6.2-cp311-cp311-win32.whl (11.4 kB view hashes)

Uploaded cp311

automap-0.6.2-cp310-cp310-win_amd64.whl (12.4 kB view hashes)

Uploaded cp310

automap-0.6.2-cp310-cp310-win32.whl (11.4 kB view hashes)

Uploaded cp310

automap-0.6.2-cp39-cp39-win_amd64.whl (12.5 kB view hashes)

Uploaded cp39

automap-0.6.2-cp39-cp39-win32.whl (11.4 kB view hashes)

Uploaded cp39

automap-0.6.2-cp38-cp38-win_amd64.whl (12.5 kB view hashes)

Uploaded cp38

automap-0.6.2-cp38-cp38-win32.whl (11.5 kB view hashes)

Uploaded cp38

automap-0.6.2-cp37-cp37m-win_amd64.whl (12.4 kB view hashes)

Uploaded cp37

automap-0.6.2-cp37-cp37m-win32.whl (11.4 kB view hashes)

Uploaded cp37

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