short-unique-id

short-unique-id 🐍⚡️

Tiny, dependency-free Snowflake-style ordered IDs and ultra-short random IDs for Python 3.9 +

Need a sortable primary-key like Twitter’s Snowflake, or just a compact URL-safe slug?
short-unique-id gives you both—without C extensions or heavy dependencies.

✨ Features

• Ordered Snowflake IDs – 64-bit, millisecond-precision, monotonic & k-sortable
• 12-char random IDs – base-62 tokens for URLs, files, IoT messages, …
• Stateless & thread-safe – no Redis, no database round-trips
• Zero dependencies – pure-Python, install in seconds
• Python 3.9 → 3.13 – fully typed, passes pytest & Ruff
• MIT licensed

🚀 Install

pip install short-unique-id

Or grab the latest dev build:

pip install git+https://github.com/Purushot14/short-unique-id.git

⚡ Quick-start

import short_unique_id as suid

# 12-character, URL-safe string (random)
slug = suid.generate_short_id()
print(slug)             # → "aZ8Ft1jK2L3q"

# Ordered, 64-bit Snowflake integer
snowflake = suid.get_next_snowflake_id()
print(snowflake)        # → 489683493715968001

Need higher entropy or longer range? Pass a custom mult (time multiplier):

slug      = suid.generate_short_id(mult=1_000_000)
snowflake = suid.get_next_snowflake_id(mult=1_000_000)

🔬 Micro-benchmark^†

Generator	Mean time / 1 000 ids	Bytes / id
short-unique-id	0.75 ms	12
uuid.uuid4()	1.90 ms	36
ulid-py (ULID)	2.15 ms	26

^{† MacBook M3, Python 3.13, single thread, timeit.repeat 5 × 1000.}

🛠️ API Reference

Function	Returns	Description	Key Args
generate_short_id(mult: int = 10_000) → str	12-char base‑62 string	Random but unique within the given time bucket.	mult – bucket size (↑ = ↑ entropy)
get_next_snowflake_id(mult: int = 10_000) → int	64-bit int	Monotonic, timestamp‑encoded Snowflake ID.	mult – ticks per ms

📚 When to use it

• Primary keys in distributed databases (fits in BIGINT)
• Short share links or invite codes
• File/folder names on S3 / GCS (lexicographic sort ≈ creation time)
• Message IDs in event streams & IoT payloads
• Anywhere you’d reach for UUIDs but want shorter or ordered IDs

🤝 Contributing

• git clone https://github.com/Purushot14/short-unique-id && cd short-unique-id
• poetry install – sets up venv & dev tools
• poetry run pytest – all green? start hacking!
• Run ruff check . --fix && ruff format . before PRs
• Open a PR – stars and issues welcome ⭐

🛡️ Pre-commit (via Poetry)

Make sure you’ve added pre-commit as a dev dependency:

poetry add --dev pre-commit

Set up the Git hook and run it against all files:

poetry run pre-commit install
poetry run pre-commit run --all-files

📝 Changelog

See CHANGELOG. Notable releases:

Version	Date	Highlights
0.2.1	2025-05-20	Python3.13 support added and Badges added on readme
0.2.0	2025-05-19	Repo rename, Poetry build, SEO README, classifiers & keywords
0.1.2	2018-11-25	Initial public release

🪪 License

Distributed under the MIT License © 2018–2025 Purushot14. See LICENSE.

Made with ❤️ for hackers who hate 36‑byte IDs.