gid128 0.0.4

GID-128 sortable 128-bit identifiers with 22-character text and opaque public tokens.

gid128

gid128 is the Python package for GID-128, a fast 128-bit sortable identifier for backend systems, databases, and APIs.

It gives you:

• 16-byte canonical binary storage for databases and joins.
• 22-character gid_s text for logs, URLs, and APIs.
• 22-character gid_x public-token text for hiding timestamp and sort order.
• Rust-native PyO3 backend for production use.

Why teams use it:

• Fast generation through the Rust-backed Python extension.
• Python benchmark results on Apple M4 / darwin arm64:

Library	Ops/sec	GID speed
gid128/generate	1.2M	1.000x
ulid-py	1.0M	1.181x slower
ksuid	907K	1.345x slower
uuid/v4	896K	1.360x slower
uuid/v7	772K	1.579x slower
nanoid	513K	2.378x slower

• Benchmarks compare against UUID v4, UUID v7, ULID, NanoID, KSUID, and other common ID generators where available.
• The benchmark gate is release-blocking and records the measured winners in the repo.
• Stable binary identity for indexing and joins.
• Public tokens that keep internal ordering out of user-facing URLs.
• Shared conformance vectors with the JS package.

Install:

uv add gid128

Basic usage:

from gid128 import gid, public_encode, public_decode

id = gid()
text = str(id)
key = bytes([1]) * 32
public_id = public_encode(id, key)
same = public_decode(public_id, key)
assert same == id

Included API surface:

• Canonical IDs: gid, parse, from_bytes, from_hex, Gid128.
• Public URL IDs: public_encode, public_decode, keyed public tokens.
• UUID-style compatibility helpers: v1, v3, v4, v5, v6, v7, validate, nil, max.
• ULID-style helpers: encode_time, decode_time, monotonic_factory, factory.
• NanoID-style helpers: custom_alphabet, custom_random, non_secure.
• Type-prefixed IDs: with_prefix, parse_prefixed, get_type, get_suffix.
• DB helpers: to_buffer, from_buffer, to_sql_hex, from_sql_hex, sql_hex_to_bytes.

Local validation:

uv sync --dev
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest --cov=gid128 --cov-report=term-missing --cov-fail-under=95
uv build
uv run python examples/basic.py

Repo-level validation:

npm run python:validate

Benchmark:

npm run bench:python

The repo-level npm run bench runs all implemented language benchmarks and writes JSON results under bench-results/.