timeflake

What it is and what it does

Timeflake is a 128-bit unique identifier that combines a 48-bit millisecond timestamp with an 80-bit cryptographically random component, designed to be both sortable and collision-resistant. Unlike UUID v1 (which leaks network info) or UUID v4 (which is random and fragments database indices), Timeflake orders by time in its most significant bits, keeping database indices compact and fast while remaining unpredictable within each millisecond.

The package provides multiple encodings—128-bit unsigned int, hex, URL-safe base62 (22 chars), and raw bytes—and is fully compatible with Python's standard uuid.UUID type. It includes optional extensions for Django ORM and Peewee, making it practical for use as a primary key in relational databases. No external dependencies are required.

Use it for:

• Use as a primary key in MySQL, Postgres, or SQLite3 to maintain insertion order and avoid index fragmentation.
• Generate unpredictable but sortable IDs for URLs and APIs where auto-increment integers are too predictable.
• Create distributed IDs across multiple machines without coordination or a centralized ID service.
• Replace UUID v4 in applications where both randomness and temporal ordering improve query performance.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates 128-bit, time-ordered, URL-safe unique identifiers (UUIDs) with millisecond-precision timestamps and cryptographic randomness, compatible with standard uuid.UUID.

Yes, if you need sortable, collision-resistant IDs for databases or URLs and want zero external dependencies. The library is stable and well-tested, but note that maintenance is dormant (last update 2023-09-01). Not suitable for security-sensitive use (password tokens, API keys); use Python's secrets module for those. Be aware that time-encoded IDs can leak privacy information about when and where content was created.

Install

timeflake on PyPI

pip install timeflake

uv add timeflake

poetry add timeflake

Installing timeflake

Before you install

Low install friction; pure Python with no runtime dependencies. Dormant maintenance (last commit 2023-09-01, 1078 days ago) but stable and archived repository shows no active development planned.

License in practice

MIT license permits commercial and private use with minimal restrictions; attribution required but no copyleft obligations.

Quickstart

import timeflake

# Create a random Timeflake
flake = timeflake.random()
print(flake.base62)  # '00mx79Rjxvfgr8qat2CeQDs'
print(flake.timestamp)  # 1579091935216

# Parse existing flake
flake = timeflake.parse(from_base62='0002HCZffkHWhKPVdXxs0YH')

Verify before relying

• Whether the 2^80 random bits per millisecond provide sufficient collision avoidance for your specific throughput and scale requirements.
• Current maintenance status and whether dormancy affects production readiness for your use case.

Package facts

Evidence: timeflake-0.4.3-py3-none-any.whl

Tags

More Python Modules packages