gh-89083: add support for UUID version 6 (RFC 9562)

Doc/library/uuid.rst

@@ -12,7 +12,7 @@
 
 This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
 and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for
-generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`.
+generating version 1, 3, 4, 5, and 6 UUIDs as specified in :rfc:`4122`.
 
 If all you want is a unique ID, you should probably call :func:`uuid1` or
 :func:`uuid4`.  Note that :func:`uuid1` may compromise privacy since it creates
@@ -149,9 +149,12 @@ which relays any information about the UUID's safety, using this enumeration:
 
 .. attribute:: UUID.version
 
-   The UUID version number (1 through 5, meaningful only when the variant is
+   The UUID version number (1 through 6, meaningful only when the variant is
    :const:`RFC_4122`).
 
+   .. versionadded:: 3.14
+      Added UUID version 6.
+
 .. attribute:: UUID.is_safe
 
    An enumeration of :class:`SafeUUID` which indicates whether the platform
@@ -216,6 +219,16 @@ The :mod:`uuid` module defines the following functions:
 
 .. index:: single: uuid5
 
+
+.. function:: uuid6(node=None, clock_seq=None)
+
+   TODO
+
+   .. versionadded:: 3.14
+
+.. index:: single: uuid6
+
+
 The :mod:`uuid` module defines the following namespace identifiers for use with
 :func:`uuid3` or :func:`uuid5`.
 

Doc/whatsnew/3.14.rst

@@ -156,6 +156,14 @@ pickle
 * Set the default protocol version on the :mod:`pickle` module to 5.
   For more details, please see :ref:`pickle protocols <pickle-protocols>`.
 
+uuid
+----
+
+* Add support for UUID version 6 via :func:`uuid.uuid6` as specified
+  in :rfc:`9562`.
+
+  (Contributed by Bénédikt Tran in :gh:`89083`.)
+
 
 Optimizations
 =============

Lib/test/test_uuid.py

@@ -267,7 +267,7 @@ def test_exceptions(self):
 
         # Version number out of range.
         badvalue(lambda: self.uuid.UUID('00'*16, version=0))
-        badvalue(lambda: self.uuid.UUID('00'*16, version=6))
+        badvalue(lambda: self.uuid.UUID('00'*16, version=42))
 
         # Integer value out of range.
         badvalue(lambda: self.uuid.UUID(int=-1))
@@ -588,15 +588,15 @@ def test_uuid1_bogus_return_value(self):
 
     def test_uuid1_time(self):
         with mock.patch.object(self.uuid, '_generate_time_safe', None), \
-             mock.patch.object(self.uuid, '_last_timestamp', None), \
+             mock.patch.object(self.uuid, '_last_timestamp_v1', None), \
              mock.patch.object(self.uuid, 'getnode', return_value=93328246233727), \
              mock.patch('time.time_ns', return_value=1545052026752910643), \
              mock.patch('random.getrandbits', return_value=5317): # guaranteed to be random
             u = self.uuid.uuid1()
             self.assertEqual(u, self.uuid.UUID('a7a55b92-01fc-11e9-94c5-54e1acf6da7f'))
 
         with mock.patch.object(self.uuid, '_generate_time_safe', None), \
-             mock.patch.object(self.uuid, '_last_timestamp', None), \
+             mock.patch.object(self.uuid, '_last_timestamp_v1', None), \
              mock.patch('time.time_ns', return_value=1545052026752910643):
             u = self.uuid.uuid1(node=93328246233727, clock_seq=5317)
             self.assertEqual(u, self.uuid.UUID('a7a55b92-01fc-11e9-94c5-54e1acf6da7f'))
@@ -681,6 +681,35 @@ def test_uuid5(self):
             equal(u, self.uuid.UUID(v))
             equal(str(u), v)
 
+    def test_uuid6(self):
+        equal = self.assertEqual
+        u = self.uuid.uuid6()
+        equal(u.variant, self.uuid.RFC_4122)
+        equal(u.version, 6)
+
+        fake_nanoseconds = 1545052026752910643
+        fake_node_value = 93328246233727
+        fake_clock_seq = 5317
+        with mock.patch.object(self.uuid, '_generate_time_safe', None), \
+                mock.patch.object(self.uuid, '_last_timestamp_v6', None), \
+                mock.patch.object(self.uuid, 'getnode', return_value=fake_node_value), \
+                mock.patch('time.time_ns', return_value=fake_nanoseconds), \
+                mock.patch('random.getrandbits', return_value=fake_clock_seq):
+            u = self.uuid.uuid6()
+            equal(u.variant, self.uuid.RFC_4122)
+            equal(u.version, 0b0110)  # 6
+
+            timestamp = 137643448267529106
+            # 32 (hi) | 16 (mid) | 12 (lo) == 60 bits of timestamp
+            equal(timestamp, 0b_00011110100100000001111111001010_0111101001010101_101110010010)
+            equal(u.time, timestamp)
+            equal(u.fields[0], 0b00011110100100000001111111001010)  # 32 high bits of time
+            equal(u.fields[1], 0b0111101001010101)  # 16 bits of time (mid)
+            equal(u.fields[2], 0b0110_101110010010)  # 4 bits of version + 12 low bits of time
+            equal(u.fields[3], 0b10_010100)  # 2 bits of variant + 6 high bits of clock_seq
+            equal(u.fields[4], 0b11000101)  # 8 low bits of clock_seq
+            equal(u.fields[5], fake_node_value)
+
     @support.requires_fork()
     def testIssue8621(self):
         # On at least some versions of OSX self.uuid.uuid4 generates

Lib/uuid.py

@@ -1,8 +1,9 @@
 r"""UUID objects (universally unique identifiers) according to RFC 4122.
 
 This module provides immutable UUID objects (class UUID) and the functions
-uuid1(), uuid3(), uuid4(), uuid5() for generating version 1, 3, 4, and 5
-UUIDs as specified in RFC 4122.
+uuid1(), uuid3(), uuid4(), uuid5() and uuid6() for generating version 1, 3,
+4, 5, and 6 UUIDs as specified in RFC 4122 (superseeded by RFC 9562 but still
+referred to as RFC 4122 for compatibility purposes).
 
 If all you want is a unique ID, you should probably call uuid1() or uuid4().
 Note that uuid1() may compromise privacy since it creates a UUID containing
@@ -129,7 +130,7 @@ class UUID:
         variant     the UUID variant (one of the constants RESERVED_NCS,
                     RFC_4122, RESERVED_MICROSOFT, or RESERVED_FUTURE)
 
-        version     the UUID version number (1 through 5, meaningful only
+        version     the UUID version number (1 through 6, meaningful only
                     when the variant is RFC_4122)
 
         is_safe     An enum indicating whether the UUID has been generated in
@@ -214,7 +215,7 @@ def __init__(self, hex=None, bytes=None, bytes_le=None, fields=None,
             if not 0 <= int < 1<<128:
                 raise ValueError('int is out of range (need a 128-bit value)')
         if version is not None:
-            if not 1 <= version <= 5:
+            if not 1 <= version <= 6:
                 raise ValueError('illegal version number')
             # Set the variant to RFC 4122.
             int &= ~(0xc000 << 48)
@@ -322,8 +323,17 @@ def clock_seq_low(self):
 
     @property
     def time(self):
-        return (((self.time_hi_version & 0x0fff) << 48) |
-                (self.time_mid << 32) | self.time_low)
+        field_1 = self.int >> 96
+        field_3_no_ver = (self.int >> 64) & 0x0fff
+
+        if self.version == 6:
+            # In version 6, the first field contains the 32 MSBs
+            # and the field after the version contains the 12 LSBs.
+            return field_1 << 28 | (self.time_mid << 12) | field_3_no_ver
+        else:
+            # In version 1, the first field contains the 32 LSBs
+            # and the field after the version contains the 12 MSBs.
+            return field_3_no_ver << 48 | (self.time_mid << 32) | field_1
 
     @property
     def clock_seq(self):
@@ -656,7 +666,7 @@ def getnode():
     assert False, '_random_getnode() returned invalid value: {}'.format(_node)
 
 
-_last_timestamp = None
+_last_timestamp_v1 = None
 
 def uuid1(node=None, clock_seq=None):
     """Generate a UUID from a host ID, sequence number, and the current time.
@@ -674,15 +684,15 @@ def uuid1(node=None, clock_seq=None):
             is_safe = SafeUUID.unknown
         return UUID(bytes=uuid_time, is_safe=is_safe)
 
-    global _last_timestamp
+    global _last_timestamp_v1
     import time
     nanoseconds = time.time_ns()
     # 0x01b21dd213814000 is the number of 100-ns intervals between the
     # UUID epoch 1582-10-15 00:00:00 and the Unix epoch 1970-01-01 00:00:00.
     timestamp = nanoseconds // 100 + 0x01b21dd213814000
-    if _last_timestamp is not None and timestamp <= _last_timestamp:
-        timestamp = _last_timestamp + 1
-    _last_timestamp = timestamp
+    if _last_timestamp_v1 is not None and timestamp <= _last_timestamp_v1:
+        timestamp = _last_timestamp_v1 + 1
+    _last_timestamp_v1 = timestamp
     if clock_seq is None:
         import random
         clock_seq = random.getrandbits(14) # instead of stable storage
@@ -719,14 +729,48 @@ def uuid5(namespace, name):
     hash = sha1(namespace.bytes + name).digest()
     return UUID(bytes=hash[:16], version=5)
 
+_last_timestamp_v6 = None
+
+def uuid6(node=None, clock_seq=None):
+    """Similar to :func:`uuid1` but where fields are ordered differently
+    for improved DB locality.
+
+    More precisely, given a 60-bit timestamp value as specified for UUIDv1,
+    for UUIDv6 the first 48 most significant bits are stored first, followed
+    by the 4-bit version (same position), followed by the remaining 12 bits
+    of the original 60-bit timestamp.
+    """
+    global _last_timestamp_v6
+    import time
+    nanoseconds = time.time_ns()
+    # 0x01b21dd213814000 is the number of 100-ns intervals between the
+    # UUID epoch 1582-10-15 00:00:00 and the Unix epoch 1970-01-01 00:00:00.
+    timestamp = nanoseconds // 100 + 0x01b21dd213814000
+    if _last_timestamp_v6 is not None and timestamp <= _last_timestamp_v6:
+        timestamp = _last_timestamp_v6 + 1
+    _last_timestamp_v6 = timestamp
+    if clock_seq is None:
+        import random
+        clock_seq = random.getrandbits(14) # instead of stable storage
+    time_hi_and_mid = (timestamp >> 12) & 0xffffffffffff
+    time_ver_and_lo = timestamp & 0x0fff
+    var_and_clock_s = clock_seq & 0x3fff
+    if node is None:
+        node = getnode()
+    int_uuid_6 = time_hi_and_mid << 80
+    int_uuid_6 |= time_ver_and_lo << 64
+    int_uuid_6 |= var_and_clock_s << 48
+    int_uuid_6 |= node & 0xffffffffffff
+    return UUID(int=int_uuid_6, version=6)
 
 def main():
     """Run the uuid command line interface."""
     uuid_funcs = {
         "uuid1": uuid1,
         "uuid3": uuid3,
         "uuid4": uuid4,
-        "uuid5": uuid5
+        "uuid5": uuid5,
+        "uuid6": uuid6,
     }
     uuid_namespace_funcs = ("uuid3", "uuid5")
     namespaces = {

Misc/NEWS.d/next/Library/2024-06-17-17-31-27.gh-issue-89083.nW00Yq.rst

@@ -0,0 +1,2 @@
+Add :func:`uuid.uuid6` for generating UUIDv6 objects as specified in
+:rfc:`9562`. Patch by Bénédikt Tran.