API Reference
hash

dbzero.hash(obj)

Computes a deterministic 64-bit integer hash for a given object.

The dbzero.hash() function generates a hash value that is guaranteed to be consistent across different Python processes and application restarts. This stability is essential for data persistence, ensuring that an object used as a key in a data structure like dbzero.dict can be reliably looked up later, even in a separate process.

<Callout type="info"> Key Difference: Unlike Python's built-in hash(), which can vary between processes due to hash randomization, dbzero.hash() is stable and predictable. This makes it suitable for use cases requiring persistent and reproducible hashing. </Callout>

Parameters

NameTypeDescription
objAnyThe object to hash. It supports a wide range of types, including standard Python primitives (str, bytes, int, Decimal), collections (tuple), datetime objects (date, time, datetime with and without timezones), Python Enum values, and their dbzero counterparts like dbzero.tuple and dbzero.enum.

Returns

A 64-bit signed integer (int) that represents the hash of the input object. Objects with the same value will always produce the same hash.

# Objects with the same value have the same hash
assert db0.hash("hello world") == db0.hash("hello world")
 
# Different objects have different hashes
assert db0.hash("hello") != db0.hash("world")

Side Effects

None. This is a pure function.

Examples

Hashing a Python Tuple

You can hash standard Python tuples containing various data types. The resulting hash will be consistent every time the program runs.

from datetime import date
 
my_tuple = (1, "string", date(2024, 8, 1))
hash_value = db0.hash(my_tuple)
 
print(hash_value)
# The output will be a consistent integer value every time

Hashing dbzero Types

The function seamlessly handles dbzero native types. This is fundamental to how dbzero.dict works, as it uses dbzero.hash internally to manage its keys.

Colors = db0.enum("Colors", ["RED", "GREEN", "BLUE"])
 
# Create a key using a db0.tuple and a db0.enum
key = db0.tuple([100, Colors.RED])
hash_value = db0.hash(key)
 
# db0.dict relies on this stable hash for lookups
data = db0.dict({key: "value for key"})
 
assert key in data

Hashing Across Processes

The key feature of dbzero.hash is its stability across process boundaries. If you run the same hash operation in two different processes, the result will be identical.

# In process_1.py
import dbzero as db0 
# ... (dbzero setup)
hash1 = db0.hash((123, "persistent_key"))
print(hash1)
# Outputs, for example: 584754972164415383
 
# In process_2.py
import dbzero as db0 
# ... (dbzero setup)
hash2 = db0.hash((123, "persistent_key"))
print(hash2)
# Also outputs: 584754972164415383
 
assert hash1 == hash2 # This will always be true
group_byindex