edwh-uuid7
A Python library that implements UUIDv7 generation and parsing.
It supports conversion to and from datetime values, ensuring full sorting compatibility with UUIDs produced by PostgreSQL’s pg_uuidv7 extension, PostgreSQL 18’s built-in uuid7, and Python 3.14’s uuid.uuid7.
Unlike the standard uuid.uuid7, this library also allows generating UUIDs for specific timestamps.
Overview
UUIDv7 is a time-sortable UUID format composed of a timestamp and random bits. Our implementation follows the UUIDv7 specification, which provides flexibility in ensuring monotonicity. We utilize microseconds for sub-millisecond precision within the timestamp; this acts as a stateless monotonic counter for UUIDs generated within the same millisecond and leaves more room for entropy compared to using nanoseconds.
UUIDv7 Layout (128 bits)
| Bits | Size (bits) | Field | Description |
|---|---|---|---|
| 0–47 | 48 | timestamp (ms) | Unix timestamp in milliseconds (sortable) |
| 48–51 | 4 | version | UUID version (0b0111 for v7) |
| 52–71 | 20 | sub-ms (μs) | Sub-millisecond fraction (0–999,999) |
| 72–127 | 56 | random | Random bits (includes UUID variant information) |
This design makes UUIDv7 globally sortable by creation time (1 μs resolution) while retaining enough entropy for distributed uniqueness.
Key Features of edwh-uuid7:
- Compatible with
pg_uuidv7’suuid_generate_v7(),uuid_v7_to_timestamptz(),uuid_timestamptz_to_v7()functions. - Sorting compatible with Python 3.14's
uuid.uuid7() - Provides conversion between
UUIDv7anddatetime. - Supports timezone-aware and naive datetime conversions.
Why this package?
The widely-used uuid7 Python package uses
a different timestamp scheme, which is not compatible with sorting behavior as implemented in the PostgreSQL
pg_uuidv7 extension. This package ensures compatibility, ensuring that UUIDv7s generated will sort correctly alongside
those produced by pg_uuidv7.
Comparison with Python 3.14's uuid7 functionality
Key differences between this library and Python 3.14's built-in uuid7:
- Timestamp Implementation: This library works with μs (microseconds), while Python 3.14+ uses a counter mechanism
- Conversion Utilities: This library provides uuid7 ↔ datetime conversion, which isn't available in the standard library implementation (at the time of writing)
- PostgreSQL Compatibility: Both implementations are sorting compatible with the
pg_uuidv7PostgreSQL extension
Installation
pip install edwh-uuid7
Usage
Here are examples of how to use edwh-uuid7:
Generating a UUIDv7
from edwh_uuid7 import uuid7 # or `uuid_generate_v7`
uuid = uuid7()
print(f"Generated UUIDv7: {uuid}")
Converting a UUIDv7 to a datetime
from edwh_uuid7 import uuid7, uuid7_to_datetime # or uuid_generate_v7, uuid_v7_to_timestamptz
uuid = uuid7() # UUID('0196905b-4434-74ef-aa27-442be7069beb')
datetime_value = uuid7_to_datetime(uuid) # datetime.datetime(2025, 5, 2, 9, 37, 2, 516000, tzinfo=datetime.timezone.utc)
print(f"Corresponding datetime: {datetime_value}") # 2025-05-02 09:37:02.516000+00:00
High-precision mode
This library provides enhanced timestamp precision capabilities:
- Default Precision: By default, uuid7 supports millisecond precision
- Enhanced Recovery: When working with UUIDs created by this library (
uuid7()oruuid7(timestamp_ns=...)), you can enablehigh_precision=Trueto recover datetime values with microsecond accuracy
Example:
now = datetime.fromtimestamp(time.time()) # datetime.datetime(2025, 5, 9, 17, 53, 50, 514106)
uuid = datetime_to_uuid7(now) # UUID('0196b5c0-c0b2-719e-802c-9964c4992a66')
uuid7_to_datetime(uuid) # datetime(2025, 5, 9, 15, 53, 50, 514000, tzinfo=datetime.timezone.utc)
uuid7_to_datetime(uuid, high_precision=True) # datetime(2025, 5, 9, 15, 53, 50, 514106, tzinfo=datetime.timezone.utc)
Converting a datetime to a UUIDv7
from edwh_uuid7.core import datetime_to_uuid7 # or uuid_timestamptz_to_v7
from datetime import datetime, timezone
dt = datetime(2025, 5, 2, 9, 37, 2, 516000, tzinfo=timezone.utc)
uuid_from_dt = datetime_to_uuid7(dt) # UUID('0196905b-4434-7000-8012-620314c8b88b')
print(f"UUIDv7 from datetime: {uuid_from_dt}") # 0196905b-4434-7000-8012-620314c8b88b
Extracting a timezone-aware datetime
from edwh_uuid7 import uuid7, uuid7_to_datetime # or uuid_generate_v7, uuid_v7_to_timestamptz
from zoneinfo import ZoneInfo
uuid = uuid7() # UUID('0196905f-0339-769a-9f0b-8fedc645a688')
datetime_value = uuid7_to_datetime(uuid, tz=ZoneInfo("Europe/Amsterdam")) # datetime.datetime(2025, 5, 2, 11, 41, 8, 25000, tzinfo=zoneinfo.ZoneInfo(key='Europe/Amsterdam'))
print(f"Generated UUID: {uuid}") # 0196905f-0339-769a-9f0b-8fedc645a688
print(f"Timezone-aware datetime: {datetime_value}") # 2025-05-02 11:41:08.025000+02:00
Caveats
While microseconds are used to ensure correct sorting, accuracy is limited (truncated) when converting back to
datetime, consistent with the behavior of the pg_uuidv7 function uuid_timestamptz_to_v7.
For example:
Input: 2025-05-02 08:46:48.307329+00:00
UUID conversion: 0196902d-45f3-7505-8038-7795a5ec9a1b (example)
Converted Back: 2025-05-02 08:46:48.307000+00:00
This truncation is by design (in favor of entropy) and aligns with the PostgreSQL pg_uuidv7 implementation.
Metadata
Release files for edwh-uuid7 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| edwh_uuid7-0.2.3.tar.gz | 7.2 kB | Without provenance | Details for edwh_uuid7-0.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| edwh_uuid7-0.2.3-py3-none-any.whl | Python 3 | none | any | Details for edwh_uuid7-0.2.3-py3-none-any.whl |
Total release size: 12.9 kB
Release files / edwh_uuid7-0.2.3.tar.gz
| Download URL | edwh_uuid7-0.2.3.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a3354ba9be573aaacfdf82f94245df41caebfecf1db9492a9cbe77b6f6e0e100
|
|
BLAKE2b-256 checksum How to use checksums |
a95385eb9f73e804eb9bec08d8092e9f5570945a5a6c9223630dbd41a59270fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.28.1
|
Release files / edwh_uuid7-0.2.3-py3-none-any.whl
| Download URL | edwh_uuid7-0.2.3-py3-none-any.whl |
|---|---|
| Size | 5.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9a2c270438af7109ba415211d190c22505fa25620cba58836b3ba3f19ef21747
|
|
BLAKE2b-256 checksum How to use checksums |
fdd3798515d597e495985f251c57ee9b550188f896f1bb5ef71838522f753842
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.28.1
|
Security for edwh-uuid7 0.2.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.