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

Doc/library/uuid.rst

@@ -1,8 +1,8 @@
-:mod:`!uuid` --- UUID objects according to :rfc:`4122`
+:mod:`!uuid` --- UUID objects according to :rfc:`9562`
 ======================================================
 
 .. module:: uuid
-   :synopsis: UUID objects (universally unique identifiers) according to RFC 4122
+   :synopsis: UUID objects (universally unique identifiers) according to RFC 9562
 .. moduleauthor:: Ka-Ping Yee <[email protected]>
 .. sectionauthor:: George Yoshida <[email protected]>
 
@@ -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 7 UUIDs as specified in :rfc:`9562`.
 
 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
@@ -65,7 +65,7 @@ which relays any information about the UUID's safety, using this enumeration:
 
    Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must be given.
    The *version* argument is optional; if given, the resulting UUID will have its
-   variant and version number set according to :rfc:`4122`, overriding bits in the
+   variant and version number set according to :rfc:`9562`, overriding bits in the
    given *hex*, *bytes*, *bytes_le*, *fields*, or *int*.
 
    Comparison of UUID objects are made by way of comparing their
@@ -137,7 +137,7 @@ which relays any information about the UUID's safety, using this enumeration:
 
 .. attribute:: UUID.urn
 
-   The UUID as a URN as specified in :rfc:`4122`.
+   The UUID as a URN as specified in :rfc:`9562`.
 
 
 .. attribute:: UUID.variant
@@ -149,7 +149,7 @@ 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 7, meaningful only when the variant is
    :const:`RFC_4122`).
 
 .. attribute:: UUID.is_safe
@@ -168,7 +168,7 @@ The :mod:`uuid` module defines the following functions:
    runs, it may launch a separate program, which could be quite slow.  If all
    attempts to obtain the hardware address fail, we choose a random 48-bit
    number with the multicast bit (least significant bit of the first octet)
-   set to 1 as recommended in :rfc:`4122`.  "Hardware address" means the MAC
+   set to 1 as recommended in :rfc:`9562`.  "Hardware address" means the MAC
    address of a network interface.  On a machine with multiple network
    interfaces, universally administered MAC addresses (i.e. where the second
    least significant bit of the first octet is *unset*) will be preferred over
@@ -216,6 +216,14 @@ The :mod:`uuid` module defines the following functions:
 
 .. index:: single: uuid5
 
+
+.. function:: uuid7()
+
+   TODO
+
+.. index:: single: uuid7
+
+
 The :mod:`uuid` module defines the following namespace identifiers for use with
 :func:`uuid3` or :func:`uuid5`.
 
@@ -252,7 +260,12 @@ of the :attr:`~UUID.variant` attribute:
 
 .. data:: RFC_4122
 
-   Specifies the UUID layout given in :rfc:`4122`.
+   Specifies the UUID layout given in :rfc:`9562`.
+
+   .. note::
+
+      For compatibility reasons, the content of the :data:`!RFC_4122` constant
+      is not updated to reflect the new RFC number.
 
 
 .. data:: RESERVED_MICROSOFT
@@ -267,7 +280,7 @@ of the :attr:`~UUID.variant` attribute:
 
 .. seealso::
 
-   :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace
+   :rfc:`9562` - A Universally Unique IDentifier (UUID) URN Namespace
       This specification defines a Uniform Resource Name namespace for UUIDs, the
       internal format of UUIDs, and methods of generating UUIDs.
 

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 7 via :func:`uuid.uuid7` as specified
+  in :rfc:`9562`.
+
+  (Contributed by Bénédikt Tran in :gh:`89083`.)
+
 
 Optimizations
 =============

Lib/test/test_uuid.py

@@ -1,3 +1,4 @@
+import random
 import unittest
 from test import support
 from test.support import import_helper
@@ -267,7 +268,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 +589,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 +682,176 @@ def test_uuid5(self):
             equal(u, self.uuid.UUID(v))
             equal(str(u), v)
 
+    def test_uuid7(self):
+        equal = self.assertEqual
+        u = self.uuid.uuid7()
+        equal(u.variant, self.uuid.RFC_4122)
+        equal(u.version, 7)
+
+        # 1 Jan 2023 12:34:56.123_456_789
+        timestamp_ns = 1672533296_123_456_789  # ns precision
+        timestamp_ms, _ = divmod(timestamp_ns, 1_000_000)
+
+        for _ in range(100):
+            counter_hi = random.getrandbits(11)
+            counter_lo = random.getrandbits(30)
+            counter = (counter_hi << 30) | counter_lo
+
+            tail = random.getrandbits(32)
+            # effective number of bits is 32 + 30 + 11 = 73
+            random_bits = counter << 32 | tail
+
+            # set all remaining MSB of fake random bits to 1 to ensure that
+            # the implementation correctly remove them
+            random_bits = (((1 << 7) - 1) << 73) | random_bits
+            random_data = random_bits.to_bytes(10)
+
+            with (
+                mock.patch.object(self.uuid, '_last_timestamp_v7', None),
+                mock.patch.object(self.uuid, '_last_counter_v7', 0),
+                mock.patch('time.time_ns', return_value=timestamp_ns),
+                mock.patch('os.urandom', return_value=random_data) as urand
+            ):
+                u = self.uuid.uuid7()
+                urand.assert_called_once_with(10)
+                equal(u.variant, self.uuid.RFC_4122)
+                equal(u.version, 7)
+
+                equal(self.uuid._last_timestamp_v7, timestamp_ms)
+                equal(self.uuid._last_counter_v7, counter)
+
+                unix_ts_ms = timestamp_ms & 0xffffffffffff
+                equal((u.int >> 80) & 0xffffffffffff, unix_ts_ms)
+
+                equal((u.int >> 75) & 1, 0)   # check that the MSB is 0
+                equal((u.int >> 64) & 0xfff, counter_hi)
+                equal((u.int >> 32) & 0x3fffffff, counter_lo)
+                equal(u.int & 0xffffffff, tail)
+
+    def test_uuid7_monotonicity(self):
+        equal = self.assertEqual
+
+        us = [self.uuid.uuid7() for _ in range(10_000)]
+        equal(us, sorted(us))
+
+        with mock.patch.multiple(self.uuid, _last_timestamp_v7=0, _last_counter_v7=0):
+            # 1 Jan 2023 12:34:56.123_456_789
+            timestamp_ns = 1672533296_123_456_789  # ns precision
+            timestamp_ms, _ = divmod(timestamp_ns, 1_000_000)
+
+            counter_hi = random.getrandbits(11)
+            counter_lo = random.getrandbits(29)  # make sure that +1 does not overflow
+            counter = (counter_hi << 30) | counter_lo
+
+            tail = random.getrandbits(32)
+            random_bits = counter << 32 | tail
+            random_data = random_bits.to_bytes(10)
+
+            with (
+                mock.patch('time.time_ns', return_value=timestamp_ns),
+                mock.patch('os.urandom', return_value=random_data) as urand
+            ):
+                u1 = self.uuid.uuid7()
+                urand.assert_called_once_with(10)
+                equal(self.uuid._last_timestamp_v7, timestamp_ms)
+                equal(self.uuid._last_counter_v7, counter)
+                equal((u1.int >> 64) & 0xfff, counter_hi)
+                equal((u1.int >> 32) & 0x3fffffff, counter_lo)
+                equal(u1.int & 0xffffffff, tail)
+
+            # 1 Jan 2023 12:34:56.123_457_032 (same millisecond but not same prec)
+            next_timestamp_ns = 1672533296_123_457_032
+            next_timestamp_ms, _ = divmod(timestamp_ns, 1_000_000)
+            equal(timestamp_ms, next_timestamp_ms)
+
+            next_tail_bytes = os.urandom(4)
+            next_fail = int.from_bytes(next_tail_bytes)
+
+            with (
+                mock.patch('time.time_ns', return_value=next_timestamp_ns),
+                mock.patch('os.urandom', return_value=next_tail_bytes) as urand
+            ):
+                u2 = self.uuid.uuid7()
+                urand.assert_called_once_with(4)
+                # same milli-second
+                equal(self.uuid._last_timestamp_v7, timestamp_ms)
+                # counter advanced by 1
+                equal(self.uuid._last_counter_v7, counter + 1)
+                equal((u2.int >> 64) & 0xfff, counter_hi)
+                equal((u2.int >> 32) & 0x3fffffff, counter_lo + 1)
+                equal(u2.int & 0xffffffff, next_fail)
+
+            self.assertLess(u1, u2)
+
+    def test_uuid7_timestamp_backwards(self):
+        equal = self.assertEqual
+        # 1 Jan 2023 12:34:56.123_456_789
+        timestamp_ns = 1672533296_123_456_789  # ns precision
+        timestamp_ms, _ = divmod(timestamp_ns, 1_000_000)
+        fake_last_timestamp_v7 = timestamp_ms + 1
+
+        counter_hi = random.getrandbits(11)
+        counter_lo = random.getrandbits(29)  # make sure that +1 does not overflow
+        counter = (counter_hi << 30) | counter_lo
+
+        tail_bytes = os.urandom(4)
+        tail = int.from_bytes(tail_bytes)
+
+        with (
+            mock.patch.object(self.uuid, '_last_timestamp_v7', fake_last_timestamp_v7),
+            mock.patch.object(self.uuid, '_last_counter_v7', counter),
+            mock.patch('time.time_ns', return_value=timestamp_ns),
+            mock.patch('os.urandom', return_value=tail_bytes) as os_urandom_fake
+        ):
+            u = self.uuid.uuid7()
+            os_urandom_fake.assert_called_once_with(4)
+            equal(u.variant, self.uuid.RFC_4122)
+            equal(u.version, 7)
+            equal(self.uuid._last_timestamp_v7, fake_last_timestamp_v7 + 1)
+            unix_ts_ms = (fake_last_timestamp_v7 + 1) & 0xffffffffffff
+            equal((u.int >> 80) & 0xffffffffffff, unix_ts_ms)
+            # counter advanced by 1
+            equal(self.uuid._last_counter_v7, counter + 1)
+            equal((u.int >> 64) & 0xfff, counter_hi)
+            # counter advanced by 1 (constructed so that counter_hi is unchanged)
+            equal((u.int >> 32) & 0x3fffffff, counter_lo + 1)
+            equal(u.int & 0xffffffff, tail)
+
+    def test_uuid7_overflow_counter(self):
+        equal = self.assertEqual
+        # 1 Jan 2023 12:34:56.123_456_789
+        timestamp_ns = 1672533296_123_456_789  # ns precision
+        timestamp_ms, _ = divmod(timestamp_ns, 1_000_000)
+
+        new_counter_hi = random.getrandbits(11)
+        new_counter_lo = random.getrandbits(30)
+        new_counter = (new_counter_hi << 30) | new_counter_lo
+
+        tail = random.getrandbits(32)
+        random_bits = new_counter << 32 | tail
+        random_data = random_bits.to_bytes(10)
+
+        with (
+            mock.patch.object(self.uuid, '_last_timestamp_v7', timestamp_ms),
+            # same timestamp, but force an overflow on the counter
+            mock.patch.object(self.uuid, '_last_counter_v7', 0x3ffffffffff),
+            mock.patch('time.time_ns', return_value=timestamp_ns),
+            mock.patch('os.urandom', return_value=random_data) as urand
+        ):
+            u = self.uuid.uuid7()
+            urand.assert_called_with(10)
+            equal(u.variant, self.uuid.RFC_4122)
+            equal(u.version, 7)
+            # timestamp advanced due to overflow
+            equal(self.uuid._last_timestamp_v7, timestamp_ms + 1)
+            unix_ts_ms = (timestamp_ms + 1) & 0xffffffffffff
+            equal((u.int >> 80) & 0xffffffffffff, unix_ts_ms)
+            # counter overflow, so we picked a new one
+            equal(self.uuid._last_counter_v7, new_counter)
+            equal((u.int >> 64) & 0xfff, new_counter_hi)
+            equal((u.int >> 32) & 0x3fffffff, new_counter_lo)
+            equal(u.int & 0xffffffff, tail)
+
     @support.requires_fork()
     def testIssue8621(self):
         # On at least some versions of OSX self.uuid.uuid4 generates