Metadata-Version: 2.4
Name: snowflake-id-toolkit
Version: 0.1.0
Summary: Snowflake ID Toolkit - Generate distributed unique IDs.
Project-URL: Homepage, https://github.com/pavelprokhorenko/snowflake-id-toolkit
Project-URL: Changelog, https://github.com/pavelprokhorenko/snowflake-id-toolkit/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/pavelprokhorenko/snowflake-id-toolkit/releases
Project-URL: Repository, https://github.com/pavelprokhorenko/snowflake-id-toolkit
Author-email: Pavel Prokhorenko <prohorenkopavel74@gmail.com>
License-File: LICENSE
Keywords: distributed,generator,id,snowflake,sonyflake,unique-id
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# snowflake-id-toolkit

A Python toolkit for generating snowflake-like unique IDs.

## Supported Implementations

- **Twitter Snowflake** - 64-bit IDs with ~69 years of timestamps, 1024 nodes, 4096 IDs per millisecond per node
- _**Instagram Snowflake** (coming soon)_
- _**Sony Sonyflake** (coming soon)_

## Installation

```bash
pip install snowflake-id-toolkit
```

## Usage

```python
from snowflake_id_toolkit.twitter import TwitterSnowflakeIDGenerator

generator = TwitterSnowflakeIDGenerator(
    node_id=0,
    epoch=1288834974657  # Twitter's default epoch
)
snowflake_id = generator.generate_next_id()
```

## Comparison with Other ID Strategies

| Feature                | Snowflake    | UUIDv4    | UUIDv7        | Auto-increment |
|------------------------|--------------|-----------|---------------|----------------|
| Size                   | 64 bits      | 128 bits  | 128 bits      | 32-64 bits     |
| Sortable by time       | ✅            | ❌         | ✅             | ✅              |
| Distributed generation | ✅            | ✅         | ✅             | ❌              |
| No coordination needed | ⚠️           | ✅         | ✅             | ❌              |
| DB Index-friendly      | ✅            | ❌         | ⚠️            | ✅              |
| Predictability         | Medium       | None      | Low           | High           |
| Throughput             | ~4M/sec/node | Unlimited | Unlimited     | DB-limited     |
| Relative speed         | ~5.2x        | ~1.1x     | 1x (baseline) | N/A (DB-bound) |

### When to Use

- **Snowflake**: High-throughput distributed systems needing compact, sortable IDs
- **UUIDv4**: When unpredictability matters, size doesn't, and no sorting needed
- **UUIDv7**: Modern default choice when simplicity is key factor and 128 bits is acceptable
- **Auto-increment**: Single-database apps where simplicity wins

## License

The **snowflake-id-toolkit** is licensed under the MIT License. See the LICENSE file for more information.
