ulid-pure

Zero-dependency pure-stdlib ULID generator and parser.

A literal port of the canonical reference implementation from github.com/ulid/spec with a thread-safe monotonic-counter ULID class extension. ULIDs are 26-character Crockford base32 strings: 48-bit millisecond Unix timestamp + 80 bits of randomness, lexicographically sortable and URL-safe.

Install

pip install -e .

Quickstart — ULID class (thread-safe, monotonic)

from ulid_pure import ULID

u = ULID()
print(u.gen())            # e.g. '01H9PZ8K3T3N5X4Y9Q2F8B7W0V'
ts_ms, randomness = u.parse('01ARZ3NDEKTSV4RRFFQ69G5FAV')

When .gen() is called multiple times within the same millisecond, the last 16 bits of the randomness increment as a monotonic counter. If the counter exceeds 65535 in one millisecond, .gen() spins until the next millisecond — overflow within a single ms is not possible.

Quickstart — low-level API

from ulid_pure import ulid_gen, ulid_decode, ulid_to_bytes, bytes_to_ulid

s = ulid_gen()                                                    # 26-char string
ts_ms, rand = ulid_decode(s)                                       # split (ts, rand)
b = ulid_to_bytes(s)                                               # 16 bytes big-endian
s2 = bytes_to_ulid(b)                                              # 16 bytes -> ULID

Acceptance / specs / citations

• ULID spec: https://github.com/ulid/spec/raw/master/README.md
• Crockford base32: https://www.crockford.com/base32.html
• RFC 4122 (UUIDs, for context): https://www.rfc-editor.org/rfc/rfc4122.txt

Limitations

• ULID().gen() raises no exception for normal use; overflow within a single millisecond (>65536 IDs in 1ms) silently advances to the next millisecond via spin-wait.
• The decode path is forgiving — I/L decode as 1, O as 0, U as 4 — per Crockford. encode never produces those characters.
• This is the canonical reference implementation ported verbatim, not a novel ULID library. Format and behaviour match ulid/spec at the time of porting.

Known Issues

The following findings were identified by an autonomous 5-card adversarial fuzzing chain (111,108 iterations across 4 harnesses). All are accepted for v0.1.0 per the HIGHEST_QUALITY_REPO contract line 316 (0 Critical/High findings → ship-with-documentation permitted).

Medium — silent data corruption on adversarial input

Low — runtime errors / spec deviations

Info — spec drift (not runtime errors)

Tests

pytest -q

147 tests collected; all green. Tests cover the three canonical ULID vectors (01ARZ3NDEKTSV4RRFFQ69G5FAV, 00000000000000000000000000, 7ZZZZZZZZZZZZZZZZZZZZZZZZ), boundary cases (epoch, max, invalid charset, monotonic same-ms, overflow, thread-safety).

License

MIT.