uuid7

uuid7 implements the version 7 UUID format proposed as an extension to RFC 4122 (Peabody/Davis draft), producing identifiers whose leading bits encode a chronologically sortable timestamp instead of pure randomness. Each UUID packs 36 bits of whole seconds, 24 bits of fractional-second precision (about 50 nanoseconds resolution), a 14-bit sequence counter for same-tick calls, and 48 bits of randomness to guarantee uniqueness.

The library exposes a small uuid_extensions module with uuid7() and uuid7str() functions that can return the identifier as a str, int, bytes, hex, or standard-library UUID object, making it a drop-in alternative to uuid.uuid4() anywhere sortable, index-friendly primary keys are useful — most notably as a database primary-key generator.

What You Get

• uuid7() function returning a time-sortable UUID as multiple output types (uuid, str, int, bytes, hex)
• uuid7str() shorthand for the common string-output case
• RFC 4122-draft-compliant version/variant bits for interoperability with existing UUID tooling
• ~50-nanosecond timestamp resolution plus a sequence counter to keep rapid successive calls ordered and unique
• Zero runtime dependencies beyond the Python standard library

Common Use Cases

• Generating time-sortable primary keys for databases to avoid B-tree index fragmentation from random UUIDv4 inserts
• Creating chronologically ordered, globally unique identifiers for distributed event or log records
• Replacing uuid.uuid4() calls where natural creation-time ordering is useful (e.g., message/job IDs)
• Producing compact, sortable identifiers for object storage keys that benefit from time-based locality

Under The Hood

Architecture - the entire implementation lives in uuid_extensions/uuid7.py (~260 lines): a uuid7() function reads the system clock, splits it into whole and fractional seconds, packs those bits alongside a monotonic per-tick sequence counter and cryptographically random bits into a 128-bit integer laid out per the RFC 4122-draft version-7 bit diagram in the README, then formats the result according to the requested as_type (uuid, str, int, bytes, hex, or None for raw bytes). Tech Stack - pure Python with no third-party runtime dependencies, packaged via a classic setup.py/setup.cfg (pre-pyproject.toml tooling), with tox and Travis CI config present for cross-version testing and sphinx docs under docs/. Code Quality - tests/test_uuid7.py is a compact ~51-line suite checking monotonic ordering, output-type correctness, and the zero-timestamp edge case; the module is small enough that its correctness is easy to audit by inspection, though the project has seen very little maintenance activity since 2021 (2 contributors, last commit February 2025). API Design - the public surface is deliberately tiny (two functions), mirroring uuid.uuid4()’s calling convention so it can be swapped in with minimal code change; the as_type parameter covering five output representations is the main ergonomic decision, trading a slightly less type-safe API for flexibility across serialization contexts.