Metadata-Version: 2.4
Name: gid128
Version: 0.0.3
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 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:

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

## Release

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

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

