Leo Vasanko fcf47d78b0 Version 1.1.0
- Made compatible with Python 3.8 (uses 3.10 typing from __future__)
- Made uuid7.time() also verify variant, to more reliably reject invalid UUIDs
- Changed repository names and links to uuid7-standard to match the package name
2025-07-04 14:56:29 -06:00
2025-07-03 14:18:58 -06:00
2025-07-04 14:56:29 -06:00
2025-07-03 14:18:58 -06:00
2025-07-04 14:56:29 -06:00

UUIDv7 for Python

A simple module for generating UUIDv7 that contain creation timestamps. Another function for extracting the time of an UUID.

Note: As of writing, Python has no UUIDv7 support. There's an abandoned package uuid7 that uses a draft RFC with incorrect timestamps (some two centuries off). These modules conflict, uninstall the other one.

  • Standard compliant: Follows the final UUIDv7 specification.
  • Pythonic: Uses stdlib datetime and UUID facilities rather than milliseconds or bare strings.

Installation

pip install uuid7-standard

Or for your project using uv:

uv add uuid7-standard

Usage

import uuid7

# Create a random UUIDv7 with current timestamp
u = uuid7.create()
print(str(u), u.bytes)

# Create with specific timestamp
from datetime import datetime, UTC

when = datetime(1970, 1, 1, tzinfo=UTC)
u = uuid7.create(when)

# Extract timestamp
from uuid import UUID

u = UUID('00000000-0000-7dac-b3e3-ecb571bb3e2f')
timestamp = uuid7.time(u)  # 1970-01-01 UTC

create(when: datetime?) -> UUID

Create a UUIDv7 with timestamp-based ordering.

The current time is used, unless when is passed as datetime (local time or timezone-aware) This is useful e.g. for creating a bunch of UUIDv7 with precisely the same timestamp.

time(u: UUID|str) -> datetime

Extract the timestamp from a UUIDv7. Raises ValueError if the UUID is not a UUIDv7.

Description
UUIDv7 generation with timestamp-based ordering for Python and timestamp extraction.
Readme 44 KiB
Languages
Python 100%