Add UUIDv8, use the official format for UUIDv7 (#66)

* Add UUIDv8 with nanosecond precision
* Change UUIDv7 to millisecond precision with increased entropy

Author: oittaa

README.md

@@ -7,7 +7,7 @@ New time-based UUID formats which are suited for use as a database key.
 [![Python versions supported](https://img.shields.io/pypi/pyversions/uuid6.svg?logo=python)](https://pypi.org/project/uuid6/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-This module extends immutable UUID objects (the UUID class) with the functions `uuid6()` and `uuid7()` from [the IETF draft][draft repository].
+This module extends immutable UUID objects (the UUID class) with the functions `uuid6()`, `uuid7()`, and `uuid8()` from [the IETF draft][draft repository].
 
 ## Install
 
@@ -18,7 +18,7 @@ pip install uuid6
 ## Usage
 
 ```python
-from uuid6 import uuid6, uuid7
+from uuid6 import uuid6, uuid7, uuid8
 
 my_uuid = uuid6()
 print(my_uuid)
@@ -27,8 +27,20 @@ assert my_uuid < uuid6()
 my_uuid = uuid7()
 print(my_uuid)
 assert my_uuid < uuid7()
+
+my_uuid = uuid8()
+print(my_uuid)
+assert my_uuid < uuid8()
 ```
 
+## Which UUID version should I use?
+
+> Implementations SHOULD utilize UUID version 7 over UUID version 1 and 6 if possible.
+
+UUID version 7 features a time-ordered value field derived from the widely implemented and well known Unix Epoch timestamp source, the number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap seconds excluded. As well as improved entropy characteristics over versions 1 or 6.
+
+If your use case requires greater granularity than UUID vesion 7 can provide, you might consider UUID version 8. UUID version 8 doesn't provide as good entropy characteristics as UUID version 7, but it utilizes timestamp with nanosecond level of precision.
+
 ## UUIDv6 Field and Bit Layout
 
 ```
@@ -47,8 +59,6 @@ assert my_uuid < uuid7()
 
 ## UUIDv7 Field and Bit Layout
 
-### [Draft 04][draft 04]
-
 ```
         0                   1                   2                   3
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
@@ -63,7 +73,7 @@ assert my_uuid < uuid7()
         +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
-### This implementation
+## UUIDv8 Field and Bit Layout
 
 ```
         0                   1                   2                   3
@@ -80,13 +90,13 @@ assert my_uuid < uuid7()
 ```
 
 - `unix_ts_ms`: 48 bit big-endian unsigned number of Unix epoch timestamp with millisecond level of precision
-- `ver`: The 4 bit UUIDv7 version (0111)
+- `ver`: The 4 bit UUIDv8 version (1000)
 - `subsec_a`: 12 bits allocated to sub-second precision values
 - `var`: 2 bit UUID variant (10)
 - `subsec_b`: 8 bits allocated to sub-second precision values
 - `rand`: The remaining 54 bits are filled with [cryptographically strong random data][python randbits]
 
- 20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts` and `subsec` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
+ 20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts_ms`, `subsec_a`,  and `subsec_b` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
 
 ## Performance
 
@@ -96,34 +106,19 @@ Run the shell script [bench.sh][bench] to test on your own machine.
 
 MacBook Air 2020
 ```
-Python 3.10.2
-Mean +- std dev: 1.02 us +- 0.01 us
-Mean +- std dev: 1.13 us +- 0.02 us
-Mean +- std dev: 2.33 us +- 0.02 us
-Mean +- std dev: 1.91 us +- 0.02 us
-+-----------+---------+-----------------------+-----------------------+-----------------------+
-| Benchmark | uuid1   | uuid4                 | uuid6                 | uuid7                 |
-+===========+=========+=======================+=======================+=======================+
-| timeit    | 1.02 us | 1.13 us: 1.11x slower | 2.33 us: 2.29x slower | 1.91 us: 1.87x slower |
-+-----------+---------+-----------------------+-----------------------+-----------------------+
-```
-
-Google [Cloud Shell][cloud shell] VM
-```
-Python 3.9.2
-Mean +- std dev: 12.6 us +- 0.5 us
-Mean +- std dev: 3.06 us +- 0.14 us
-Mean +- std dev: 6.42 us +- 0.37 us
-Mean +- std dev: 4.94 us +- 0.24 us
-+-----------+---------+-----------------------+-----------------------+-----------------------+
-| Benchmark | uuid1   | uuid4                 | uuid6                 | uuid7                 |
-+===========+=========+=======================+=======================+=======================+
-| timeit    | 12.6 us | 3.06 us: 4.11x faster | 6.42 us: 1.95x faster | 4.94 us: 2.54x faster |
-+-----------+---------+-----------------------+-----------------------+-----------------------+
+Python 3.10.4
+Mean +- std dev: 870 ns +- 11 ns
+Mean +- std dev: 1.17 us +- 0.01 us
+Mean +- std dev: 2.18 us +- 0.02 us
+Mean +- std dev: 1.60 us +- 0.02 us
+Mean +- std dev: 1.78 us +- 0.02 us
++-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+
+| Benchmark | uuid1  | uuid4                 | uuid6                 | uuid7                 | uuid8                 |
++===========+========+=======================+=======================+=======================+=======================+
+| timeit    | 870 ns | 1.17 us: 1.35x slower | 2.18 us: 2.51x slower | 1.60 us: 1.84x slower | 1.78 us: 2.04x slower |
++-----------+--------+-----------------------+-----------------------+-----------------------+-----------------------+
 ```
 
-[draft repository]: https://github.com/uuid6/uuid6-ietf-draft
-[draft 04]: https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.2
-[cloud shell]: https://cloud.google.com/shell/docs
+[draft repository]: https://github.com/ietf-wg-uuidrev/rfc4122bis
 [python randbits]: https://docs.python.org/3/library/secrets.html#secrets.randbits
 [bench]: https://github.com/oittaa/uuid6-python/blob/main/bench.sh

bench.sh

@@ -6,5 +6,6 @@ python -m pyperf timeit -q -o "${TESTDIR}/uuid1.json" -s "import uuid" "uuid.uui
 python -m pyperf timeit -q -o "${TESTDIR}/uuid4.json" -s "import uuid" "uuid.uuid4()"
 python -m pyperf timeit -q -o "${TESTDIR}/uuid6.json" -s "import uuid6" "uuid6.uuid6()"
 python -m pyperf timeit -q -o "${TESTDIR}/uuid7.json" -s "import uuid6" "uuid6.uuid7()"
-python -m pyperf compare_to --table "${TESTDIR}/uuid1.json" "${TESTDIR}/uuid4.json" "${TESTDIR}/uuid6.json" "${TESTDIR}/uuid7.json"
+python -m pyperf timeit -q -o "${TESTDIR}/uuid8.json" -s "import uuid6" "uuid6.uuid8()"
+python -m pyperf compare_to --table "${TESTDIR}/uuid1.json" "${TESTDIR}/uuid4.json" "${TESTDIR}/uuid6.json" "${TESTDIR}/uuid7.json" "${TESTDIR}/uuid8.json"
 rm -rf -- "${TESTDIR}"

src/uuid6/__init__.py

@@ -39,7 +39,7 @@ def __init__(
         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 6 <= version <= 7:
+            if not 6 <= version <= 8:
                 raise ValueError("illegal version number")
             # Set the variant to RFC 4122.
             int &= ~(0xC000 << 48)
@@ -62,6 +62,8 @@ def time(self) -> int:
                 | (self.time_hi_version & 0x0FFF)
             )
         if self.version == 7:
+            return self.int >> 80
+        if self.version == 8:
             return (self.int >> 80) * 10**6 + _subsec_decode(self.subsec)
         return super().time
 
@@ -76,12 +78,13 @@ def _subsec_encode(value: int) -> int:
 
 _last_v6_timestamp = None
 _last_v7_timestamp = None
+_last_v8_timestamp = None
 
 
 def uuid6(clock_seq: int = None) -> UUID:
     r"""UUID version 6 is a field-compatible version of UUIDv1, reordered for
-    improved DB locality.  It is expected that UUIDv6 will primarily be
-    used in contexts where there are existing v1 UUIDs.  Systems that do
+    improved DB locality. It is expected that UUIDv6 will primarily be
+    used in contexts where there are existing v1 UUIDs. Systems that do
     not involve legacy UUIDv1 SHOULD consider using UUIDv7 instead.
 
     If 'clock_seq' is given, it is used as the sequence number;
@@ -98,21 +101,20 @@ def uuid6(clock_seq: int = None) -> UUID:
     _last_v6_timestamp = timestamp
     if clock_seq is None:
         clock_seq = secrets.randbits(14)  # instead of stable storage
-    node = secrets.randbits(48)
     time_high_and_time_mid = (timestamp >> 12) & 0xFFFFFFFFFFFF
     time_low_and_version = timestamp & 0x0FFF
     uuid_int = time_high_and_time_mid << 80
     uuid_int |= time_low_and_version << 64
     uuid_int |= (clock_seq & 0x3FFF) << 48
-    uuid_int |= node
+    uuid_int |= secrets.randbits(48)
     return UUID(int=uuid_int, version=6)
 
 
 def uuid7() -> UUID:
     r"""UUID version 7 features a time-ordered value field derived from the
     widely implemented and well known Unix Epoch timestamp source, the
     number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap
-    seconds excluded.  As well as improved entropy characteristics over
+    seconds excluded. As well as improved entropy characteristics over
     versions 1 or 6.
 
     Implementations SHOULD utilize UUID version 7 over UUID version 1 and
@@ -121,16 +123,33 @@ def uuid7() -> UUID:
     global _last_v7_timestamp
 
     nanoseconds = time.time_ns()
-    if _last_v7_timestamp is not None and nanoseconds <= _last_v7_timestamp:
-        nanoseconds = _last_v7_timestamp + 1
-    _last_v7_timestamp = nanoseconds
+    timestamp_ms, _ = divmod(nanoseconds, 10**6)
+    if _last_v7_timestamp is not None and timestamp_ms <= _last_v7_timestamp:
+        timestamp_ms = _last_v7_timestamp + 1
+    _last_v7_timestamp = timestamp_ms
+    uuid_int = (timestamp_ms & 0xFFFFFFFFFFFF) << 80
+    uuid_int |= secrets.randbits(76)
+    return UUID(int=uuid_int, version=7)
+
+
+def uuid8() -> UUID:
+    r"""UUID version 8 features a time-ordered value field derived from the
+    widely implemented and well known Unix Epoch timestamp source, the
+    number of nanoseconds seconds since midnight 1 Jan 1970 UTC, leap
+    seconds excluded."""
+
+    global _last_v8_timestamp
+
+    nanoseconds = time.time_ns()
+    if _last_v8_timestamp is not None and nanoseconds <= _last_v8_timestamp:
+        nanoseconds = _last_v8_timestamp + 1
+    _last_v8_timestamp = nanoseconds
     timestamp_ms, timestamp_ns = divmod(nanoseconds, 10**6)
     subsec = _subsec_encode(timestamp_ns)
     subsec_a = subsec >> 8
     subsec_b = subsec & 0xFF
-    rand = secrets.randbits(54)
     uuid_int = (timestamp_ms & 0xFFFFFFFFFFFF) << 80
     uuid_int |= subsec_a << 64
     uuid_int |= subsec_b << 54
-    uuid_int |= rand
-    return UUID(int=uuid_int, version=7)
+    uuid_int |= secrets.randbits(54)
+    return UUID(int=uuid_int, version=8)

test/test_uuid6.py

@@ -3,10 +3,11 @@
 from unittest.mock import patch
 from uuid import uuid1
 
-from uuid6 import UUID, uuid6, uuid7
+from uuid6 import UUID, uuid6, uuid7, uuid8
 
 REGEX_UUID6 = r"^[0-9a-f]{8}-[0-9a-f]{4}-6[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
 REGEX_UUID7 = r"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+REGEX_UUID8 = r"^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
 YEAR_IN_NS = 3600 * 24 * 36525 * 10**7
 
 
@@ -29,6 +30,15 @@ def test_uuid7_generation(self):
             self.assertLess(uuid7_1, uuid7_2)
             uuid7_1 = uuid7_2
 
+    def test_uuid8_generation(self):
+        uuid8_1 = uuid8()
+        self.assertEqual(uuid8_1.version, 8)
+        for _ in range(1000):
+            self.assertRegex(str(uuid8_1), REGEX_UUID8)
+            uuid8_2 = uuid8()
+            self.assertLess(uuid8_1, uuid8_2)
+            uuid8_1 = uuid8_2
+
     def test_invalid_int(self):
         with self.assertRaises(ValueError):
             _ = UUID(int=-1)
@@ -55,6 +65,15 @@ def test_uuid7_same_nanosecond(self, mocktime):
             self.assertLess(uuid7_1, uuid7_2)
             uuid7_1 = uuid7_2
 
+    @patch("uuid6._last_v8_timestamp", 1)
+    @patch("time.time_ns", return_value=1234)
+    def test_uuid8_same_nanosecond(self, mocktime):
+        uuid8_1 = uuid8()
+        for _ in range(1000):
+            uuid8_2 = uuid8()
+            self.assertLess(uuid8_1, uuid8_2)
+            uuid8_1 = uuid8_2
+
     @patch("uuid6._last_v6_timestamp", 1)
     @patch("secrets.randbits", return_value=678)
     @patch("time.time_ns", return_value=12345)
@@ -96,25 +115,41 @@ def test_uuid7_far_in_future(self):
                 self.assertLess(uuid_prev, uuid_cur)
                 uuid_prev = uuid_cur
 
+    @patch("uuid6._last_v8_timestamp", 1)
+    def test_uuid8_far_in_future(self):
+        with patch("time.time_ns", return_value=1):
+            uuid_prev = uuid8()
+        for i in range(1, 8000, 10):
+            with patch("time.time_ns", return_value=i * YEAR_IN_NS):
+                uuid_cur = uuid8()
+                self.assertLess(uuid_prev, uuid_cur)
+                uuid_prev = uuid_cur
+
     def test_time(self):
         uuid_1 = uuid1()
         uuid_6 = uuid6()
         self.assertAlmostEqual(uuid_6.time / 10**7, uuid_1.time / 10**7, 3)
         cur_time = time_ns()
         uuid_7 = uuid7()
-        self.assertAlmostEqual(uuid_7.time / 10**9, cur_time / 10**9, 3)
+        self.assertAlmostEqual(uuid_7.time / 10**3, cur_time / 10**9, 2)
+        uuid_8 = uuid8()
+        self.assertAlmostEqual(uuid_8.time / 10**9, cur_time / 10**9, 3)
 
     def test_zero_time(self):
         uuid_6 = UUID(hex="00000000-0000-6000-8000-000000000000")
         self.assertEqual(uuid_6.time, 0)
         uuid_7 = UUID(hex="00000000-0000-7000-8000-000000000000")
         self.assertEqual(uuid_7.time, 0)
+        uuid_8 = UUID(hex="00000000-0000-8000-8000-000000000000")
+        self.assertEqual(uuid_8.time, 0)
 
     def test_max_time(self):
         uuid_6 = UUID(hex="ffffffff-ffff-6fff-bfff-ffffffffffff")
         self.assertEqual(uuid_6.time, 1152921504606846975)
         uuid_7 = UUID(hex="ffffffff-ffff-7fff-bfff-ffffffffffff")
-        self.assertEqual(uuid_7.time, 281474976710656000000)
+        self.assertEqual(uuid_7.time, 281474976710655)
+        uuid_8 = UUID(hex="ffffffff-ffff-8fff-bfff-ffffffffffff")
+        self.assertEqual(uuid_8.time, 281474976710656000000)
 
     def test_multiple_arguments(self):
         with self.assertRaises(TypeError):

test/test_vectors.py

@@ -6,7 +6,7 @@
 
 class TestVectors(unittest.TestCase):
     """
-    https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#appendix-B
+    https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#appendix-C
     """
 
     @patch("uuid6._last_v6_timestamp", 1)
@@ -17,10 +17,11 @@ def test_uuid6_hex_from_time(self, mocktime, mockrand):
         self.assertEqual(str(uuid_6), "1ec9414c-232a-6b00-b3c8-9e6bdeced846")
 
     @patch("uuid6._last_v7_timestamp", 1)
+    @patch("secrets.randbits", return_value=0xCC3 << 64 | 0x1 << 60 | 0x8C4DC0C0C07398F)
     @patch("time.time_ns", return_value=0x17F22E279B0 * 10**6)
-    def test_uuid7_hex_from_time(self, mocktime):
+    def test_uuid7_hex_from_time(self, mocktime, mockrand):
         uuid_7 = uuid7()
-        self.assertEqual(str(uuid_7)[:15], "017f22e2-79b0-7")
+        self.assertEqual(str(uuid_7), "017f22e2-79b0-7cc3-98c4-dc0c0c07398f")
 
     def test_uuid6_time_from_hex(self):
         uuid_6 = UUID(hex="1EC9414C-232A-6B00-B3C8-9E6BDECED846")
@@ -30,7 +31,7 @@ def test_uuid6_time_from_hex(self):
 
     def test_uuid7_time_from_hex(self):
         uuid_7 = UUID(hex="017F22E2-79B0-7CC3-98C4-DC0C0C07398F")
-        self.assertEqual(uuid_7.time // 10**6, 1645557742000)
+        self.assertEqual(uuid_7.time, 1645557742000)
 
 
 if __name__ == "__main__":