Skip to content

gh-130843: expose 48-bit timestamp for UUIDv7 #131838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 31, 2025
Merged

gh-130843: expose 48-bit timestamp for UUIDv7 #131838

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3054a85
expose 48-bit timestamp for UUIDv7
picnixz Mar 26, 2025
91d659f
Update Doc/library/uuid.rst
picnixz Mar 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions Doc/library/uuid.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,28 +103,29 @@ which relays any information about the UUID's safety, using this enumeration:
- Meaning

* - .. attribute:: UUID.time_low
- The first 32 bits of the UUID.
- The first 32 bits of the UUID. Only relevant to version 1.

* - .. attribute:: UUID.time_mid
- The next 16 bits of the UUID.
- The next 16 bits of the UUID. Only relevant to version 1.

* - .. attribute:: UUID.time_hi_version
- The next 16 bits of the UUID.
- The next 16 bits of the UUID. Only relevant to version 1.

* - .. attribute:: UUID.clock_seq_hi_variant
- The next 8 bits of the UUID.
- The next 8 bits of the UUID. Only relevant to versions 1 and 6.

* - .. attribute:: UUID.clock_seq_low
- The next 8 bits of the UUID.
- The next 8 bits of the UUID. Only relevant to versions 1 and 6.

* - .. attribute:: UUID.node
- The last 48 bits of the UUID.
- The last 48 bits of the UUID. Only relevant to version 1.

* - .. attribute:: UUID.time
- The 60-bit timestamp.
- The 60-bit timestamp for version 1 and 6.
- The 48-bit timestamp for version 7.

* - .. attribute:: UUID.clock_seq
- The 14-bit sequence number.
- The 14-bit sequence number. Only relevant to versions 1 and 6.


.. attribute:: UUID.hex
Expand Down
5 changes: 5 additions & 0 deletions Lib/test/test_uuid.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -913,6 +913,7 @@ def test_uuid7(self):
equal(self.uuid._last_counter_v7, counter)

unix_ts_ms = timestamp_ms & 0xffff_ffff_ffff
equal(u.time, unix_ts_ms)
equal((u.int >> 80) & 0xffff_ffff_ffff, unix_ts_ms)

equal((u.int >> 75) & 1, 0) # check that the MSB is 0
Expand Down Expand Up @@ -966,6 +967,7 @@ def test_uuid7_monotonicity(self):
urand.assert_called_once_with(10)
equal(self.uuid._last_timestamp_v7, timestamp_ms)
equal(self.uuid._last_counter_v7, counter)
equal(u1.time, timestamp_ms)
equal((u1.int >> 64) & 0xfff, counter_hi)
equal((u1.int >> 32) & 0x3fff_ffff, counter_lo)
equal(u1.int & 0xffff_ffff, tail)
Expand All @@ -988,6 +990,7 @@ def test_uuid7_monotonicity(self):
equal(self.uuid._last_timestamp_v7, timestamp_ms)
# 42-bit counter advanced by 1
equal(self.uuid._last_counter_v7, counter + 1)
equal(u2.time, timestamp_ms)
equal((u2.int >> 64) & 0xfff, counter_hi)
equal((u2.int >> 32) & 0x3fff_ffff, counter_lo + 1)
equal(u2.int & 0xffff_ffff, next_fail)
Expand Down Expand Up @@ -1025,6 +1028,7 @@ def test_uuid7_timestamp_backwards(self):
equal(u.version, 7)
equal(self.uuid._last_timestamp_v7, fake_last_timestamp_v7 + 1)
unix_ts_ms = (fake_last_timestamp_v7 + 1) & 0xffff_ffff_ffff
equal(u.time, unix_ts_ms)
equal((u.int >> 80) & 0xffff_ffff_ffff, unix_ts_ms)
# 42-bit counter advanced by 1
equal(self.uuid._last_counter_v7, counter + 1)
Expand Down Expand Up @@ -1064,6 +1068,7 @@ def test_uuid7_overflow_counter(self):
# timestamp advanced due to overflow
equal(self.uuid._last_timestamp_v7, timestamp_ms + 1)
unix_ts_ms = (timestamp_ms + 1) & 0xffff_ffff_ffff
equal(u.time, unix_ts_ms)
equal((u.int >> 80) & 0xffff_ffff_ffff, unix_ts_ms)
# counter overflowed, so we picked a new one
equal(self.uuid._last_counter_v7, new_counter)
Expand Down
19 changes: 15 additions & 4 deletions Lib/uuid.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,16 @@ class UUID:

fields a tuple of the six integer fields of the UUID,
which are also available as six individual attributes
and two derived attributes. The time_* attributes are
only relevant to version 1, while the others are only
relevant to versions 1 and 6:
and two derived attributes. Those attributes are not
always relevant to all UUID versions:

The 'time_*' attributes are only relevant to version 1.

The 'clock_seq*' and 'node' attributes are only relevant
to versions 1 and 6.

The 'time' attribute is only relevant to versions 1, 6
and 7.

time_low the first 32 bits of the UUID
time_mid the next 16 bits of the UUID
Expand All @@ -145,7 +152,8 @@ class UUID:
clock_seq_low the next 8 bits of the UUID
node the last 48 bits of the UUID

time the 60-bit timestamp
time the 60-bit timestamp for UUIDv1/v6,
or the 48-bit timestamp for UUIDv7
clock_seq the 14-bit sequence number

hex the UUID as a 32-character hexadecimal string
Expand Down Expand Up @@ -366,6 +374,9 @@ def time(self):
time_hi = self.int >> 96
time_lo = (self.int >> 64) & 0x0fff
return time_hi << 28 | (self.time_mid << 12) | time_lo
elif self.version == 7:
# unix_ts_ms (48) | ... (80)
return self.int >> 80
else:
# time_lo (32) | time_mid (16) | ver (4) | time_hi (12) | ... (64)
#
Expand Down
Loading