svix-ksuid

svix-ksuid is a pure-Python implementation of KSUID — a K-sortable unique identifier that embeds a timestamp so IDs generated close together in time sort together lexically, unlike random UUIDs. It’s maintained by Svix (the webhooks-as-a-service company) and mirrors their Rust and Go KSUID implementations, producing IDs fully compatible with Segment’s original KSUID spec.

The library exposes a simple Ksuid class plus a higher-precision KsuidMs variant (millisecond-ish accuracy instead of KSUID’s default 1-second resolution), both usable as drop-in identifiers wherever a sortable, collision-resistant unique ID is needed.

What You Get

• Ksuid class implementing the standard 1-second-accuracy KSUID spec, fully compatible with Segment’s reference implementation
• KsuidMs variant trading one payload byte for roughly 4ms timestamp accuracy while remaining valid, standard KSUIDs
• Construction from an explicit datetime for deterministic/backfilled ID generation, alongside default “now” generation
• Access to the decoded .datetime, .timestamp, .payload, and raw bytes() representation of any KSUID instance
• Type-checked package (py.typed) for use in fully-typed Python codebases via mypy

Common Use Cases

• Generating primary keys or event IDs that are both globally unique and naturally sortable by creation time, without a separate timestamp column
• Producing idempotency keys or trace IDs for webhook and event-driven systems where roughly-chronological ordering matters (Svix’s own primary use case)
• Replacing auto-increment or random UUID primary keys in distributed systems where centralized ID coordination isn’t available
• Cross-language ID consistency, since the same KSUID values can be generated and parsed identically from Svix’s Python, Rust, and Go implementations

Under The Hood

Architecture The entire implementation lives in ksuid/ksuid.py: a Ksuid class packs a 4-byte big-endian timestamp offset (from a custom KSUID epoch) with a fixed-length random payload into a byte buffer, base62-encodes it for string representation, and exposes decoded .timestamp/.datetime/.payload properties; KsuidMs subclasses or parallels this with an adjusted byte layout that trades payload entropy for sub-second timestamp resolution, and ksuid/__init__.py re-exports both as the public API.

Tech Stack It’s dependency-free pure Python (no runtime dependencies beyond the standard library), managed with uv/pyproject.toml, type-annotated with a py.typed marker and checked via mypy.ini, and published to PyPI as svix-ksuid while the importable module name is simply ksuid.

Code Quality Tests live under tests/ (test_ksuid.py, smoke_test.py) including a fixture file of known-good KSUID values (test_kuids.txt) to check spec-compatibility against reference implementations, with lint and test GitHub Actions workflows gating changes; the codebase is intentionally tiny and single-purpose, which keeps the surface easy to audit end-to-end.

API Design The API mirrors Python’s own ID/UUID ergonomics closely — Ksuid() for a default instance, Ksuid(datetime) for a specific time, string/bytes conversion via str()/bytes() — so the switch from uuid.uuid4()-style code to sortable KSUIDs requires almost no new concepts to learn.