sparkid 1.0.0

Fast, time-sortable, 22-char Base58 unique ID generator

sparkid

Fast, time-sortable, 22-char Base58 unique ID generator. Zero dependencies.

1ocYKWj8qj8XxUmCeZ9cHo
1ocYKWj8MvH3wKafkuX8V7
1ocYKWj8RGe6aGYLZ7ScYY

Install

pip install sparkid

Usage

from sparkid import generate_id

id = generate_id()
# => "1ocYKWj8qj8XxUmCeZ9cHo"

Properties

Property	Value
Length	22 characters, fixed
Alphabet	Base58 (no 0, O, I, l)
Sortable	Lexicographically, by creation time
URL-safe	Yes
Collision resistance	~58^14 (~1.8 x 10^24) combinations per millisecond
Randomness	Cryptographically secure (os.urandom)
Thread-safe	Yes (via threading.local)

How it works

Each ID is composed of two parts:

[8-char timestamp][14-char random]

• Timestamp (8 chars): Current time in milliseconds, Base58-encoded. IDs generated later always sort after earlier ones.
• Random (14 chars): Rejection-sampled from os.urandom with no modulo bias. Ensures uniqueness even within the same millisecond.

Advanced usage

For manual control, use the IdGenerator class directly:

from sparkid import IdGenerator

gen = IdGenerator()
id = gen()

Each IdGenerator instance maintains its own internal state. The module-level generate_id() function uses threading.local to automatically create one instance per thread.

Performance

~2.5 million IDs/sec on Python 3.12 (~0.4 us/call):

python bench/benchmark.py

License

MIT