preshed: Cython Hash Table for Pre-Hashed Keys

Simple but high performance Cython hash table mapping pre-randomized keys to void* values. Inspired by Jeff Preshing.

All Python APIs provded by the BloomFilter and PreshMap classes are thread-safe on both the GIL-enabled build and the free-threaded build of Python 3.14 and newer. If you use the C API or the PreshCounter class, you must provide external synchronization if you use the data structures by this library in a multithreaded environment.

Installation

pip install preshed --only-binary preshed

Or with conda:

conda install -c conda-forge preshed

Usage

PreshMap

A hash map for pre-hashed keys, mapping uint64 to uint64 values.

frompreshed.mapsimportPreshMapmap=PreshMap() # create with default sizemap=PreshMap(initial_size=1024) # create with initial capacity (must be power of 2)map[key] =value# set a valuevalue=map[key] # get a value (returns None if missing)value=map.pop(key) # remove and return a valuedelmap[key] # delete a keykeyinmap# membership testlen(map) # number of entriesforkeyinmap: # iterate over keyspassforkey, valueinmap.items(): # iterate over key-value pairspassforvalueinmap.values(): # iterate over valuespass

BloomFilter

A probabilistic set for fast membership testing of integer keys.

frompreshed.bloomimportBloomFilterbloom=BloomFilter(size=1024, hash_funcs=23) # explicit parametersbloom=BloomFilter.from_error_rate(10000, error_rate=1e-4) # auto-sizedbloom.add(42) # add a key42inbloom# membership test (may have false positives)data=bloom.to_bytes() # serializebloom.from_bytes(data) # deserialize in-place

PreshCounter

A counter backed by a hash map, for counting occurrences of uint64 keys.

frompreshed.counterimportPreshCountercounter=PreshCounter()
counter.inc(key, 1) # increment key by 1count=counter[key] # get current countlen(counter) # number of bucketsforkey, countincounter: # iterate over entriespasscounter.smooth() # apply Good-Turing smoothingprob=counter.prob(key) # get smoothed probability

Cython API

All classes expose a C-level API via .pxd files for use in Cython extensions. The low-level MapStruct and BloomStruct functions operate on raw structs and can be called without the GIL:

from preshed.maps cimport PreshMap, map_get, map_set, map_iter, key_t
from preshed.bloom cimport BloomFilter, bloom_add, bloom_contains
cdef PreshMap table = PreshMap()
# Low-level nogil access (requires external synchronization)
cdef void* value
with nogil:
value = map_get(table.c_map, some_key)