Metadata-Version: 2.4
Name: gid128
Version: 0.0.4
Requires-Dist: cryptography>=42
Summary: GID-128 sortable 128-bit identifiers with 22-character text and opaque public tokens.
Keywords: gid,uuid,ulid,id,sortable,identifier
Author: GID-128 contributors
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/gid128/gid128
Project-URL: Repository, https://github.com/gid128/gid128

# 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:

```bash
uv add gid128
```

Basic usage:

```python
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:

```bash
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:

```bash
npm run python:validate
```

Benchmark:

```bash
npm run bench:python
```

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

