gid128 0.0.3

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

gid128

gid128 is the Python package for GID-128, a 128-bit sortable identifier with:

• 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.

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/.

Release

Release a new version from packages/python after updating pyproject.toml to the next version. For example, to publish 0.0.3:

cd packages/python
uv version 0.0.3
uv sync --dev
uv run ruff check .
uv run ty check
uv run pytest
uv build
uvx twine check dist/*
uvx twine upload dist/*

If PyPI asks for credentials:

• Username: __token__
• Password: your PyPI API token

If you use Trusted Publishing instead of a token, keep the upload step but let PyPI verify the project identity through its configured publisher.