Python UUIDv7: time-ordered IDs without treating them as a clock

Operation contract

Two new order IDs are generated and decoded. Both have version seven, distinct bytes, and nondecreasing embedded millisecond times in this process. The program prints properties rather than the IDs themselves because the values depend on the run.

Failure boundary

An ID is not an authorization token or proof that an order existed at the embedded time. Clocks can shift, distinct hosts have no single strict issue order, and an attacker can construct a UUID with chosen bits. Store a trusted creation timestamp separately when audit or cross-host ordering matters.

Working program

import uuid

first_order_id = uuid.uuid7()
second_order_id = uuid.uuid7()
print("versions", first_order_id.version, second_order_id.version)
print("distinct", first_order_id != second_order_id)
print("time_non_decreasing", first_order_id.time <= second_order_id.time)

Output

versions 7 7
distinct True
time_non_decreasing True

Costs and limits

Generation uses a fixed-size identifier and constant-size metadata. Sorting many IDs still costs O(n log n), and a timestamp component does not eliminate an indexed database access path.

Common Mistakes

• Do not make access decisions from an ID's timestamp bits.
• Do not claim a global strict order across independent hosts.
• Do not equate a generated ID with a durable database commit.

Connected lessons

• Python compatibility checks: parse syntax and execute contracts as separate evidence
• Python sqlite3 transactions: bind values and roll back failed batches
• Python datetime: require an offset before comparing timestamps

Test this contract.