Metadata-Version: 2.4
Name: sparkid
Version: 1.0.0
Summary: Fast, time-sortable, 22-char Base58 unique ID generator
Project-URL: Homepage, https://github.com/youssefm/sparkid
Project-URL: Repository, https://github.com/youssefm/sparkid
License-Expression: MIT
Keywords: base58,id,ksuid,sortable,ulid,unique,uuid
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# sparkid

Fast, time-sortable, 22-char Base58 unique ID generator. Zero dependencies.

```
1ocYKWj8qj8XxUmCeZ9cHo
1ocYKWj8MvH3wKafkuX8V7
1ocYKWj8RGe6aGYLZ7ScYY
```

## Install

```bash
pip install sparkid
```

## Usage

```python
from sparkid import generate_id

id = generate_id()
# => "1ocYKWj8qj8XxUmCeZ9cHo"
```

## Properties

| Property | Value |
|---|---|
| **Length** | 22 characters, fixed |
| **Alphabet** | Base58 (no `0`, `O`, `I`, `l`) |
| **Sortable** | Lexicographically, by creation time |
| **URL-safe** | Yes |
| **Collision resistance** | ~58^14 (~1.8 x 10^24) combinations per millisecond |
| **Randomness** | Cryptographically secure (`os.urandom`) |
| **Thread-safe** | Yes (via `threading.local`) |

## How it works

Each ID is composed of two parts:

```
[8-char timestamp][14-char random]
```

- **Timestamp** (8 chars): Current time in milliseconds, Base58-encoded. IDs generated later always sort after earlier ones.
- **Random** (14 chars): Rejection-sampled from `os.urandom` with no modulo bias. Ensures uniqueness even within the same millisecond.

## Advanced usage

For manual control, use the `IdGenerator` class directly:

```python
from sparkid import IdGenerator

gen = IdGenerator()
id = gen()
```

Each `IdGenerator` instance maintains its own internal state. The module-level `generate_id()` function uses `threading.local` to automatically create one instance per thread.

## Performance

~2.5 million IDs/sec on Python 3.12 (~0.4 us/call):

```bash
python bench/benchmark.py
```

## License

MIT
