Add uuid1_to_uuid6() function (#107)

Author: oittaa

README.md

@@ -18,19 +18,24 @@ pip install uuid6
 ## Usage
 
 ```python
-from uuid6 import uuid6, uuid7, uuid8
+import uuid6
 
-my_uuid = uuid6()
+my_uuid = uuid6.uuid6()
 print(my_uuid)
-assert my_uuid < uuid6()
+assert my_uuid < uuid6.uuid6()
 
-my_uuid = uuid7()
+my_uuid = uuid6.uuid7()
 print(my_uuid)
-assert my_uuid < uuid7()
+assert my_uuid < uuid6.uuid7()
 
-my_uuid = uuid8()
+my_uuid = uuid6.uuid8()
 print(my_uuid)
-assert my_uuid < uuid8()
+assert my_uuid < uuid6.uuid8()
+
+import uuid
+
+my_uuid = uuid.UUID(hex="C232AB00-9414-11EC-B3C8-9E6BDECED846")
+assert uuid6.uuid1_to_uuid6(my_uuid) == uuid.UUID(hex="1EC9414C-232A-6B00-B3C8-9E6BDECED846")
 ```
 
 ## Which UUID version should I use?
@@ -41,6 +46,24 @@ UUID version 7 features a time-ordered value field derived from the widely imple
 
 If your use case requires greater granularity than UUID version 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.
 
+## Functions
+
+### uuid6.uuid1_to_uuid6(*uuid1*)
+
+Generate a UUID version 6 object from a UUID version 1 object.
+
+### uuid6.uuid6(*clock_seq=None*)
+
+Generate a UUID from a random number, sequence number, and the current time. If *clock_seq* is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen.
+
+### uuid6.uuid7()
+
+Generate a UUID from a random number, and the current time.
+
+### uuid6.uuid8()
+
+Generate a UUID from a random number, and the current time.
+
 ## UUID Version 6
 
 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 not involve legacy UUIDv1 **SHOULD** use UUIDv7 instead.

src/uuid6/__init__.py

@@ -78,6 +78,20 @@ def _subsec_encode(value: int) -> int:
     return value * 2**20 // 10**6
 
 
+def uuid1_to_uuid6(uuid1: uuid.UUID) -> UUID:
+    r"""Generate a UUID version 6 object from a UUID version 1 object."""
+    if uuid1.version != 1:
+        raise ValueError("given UUID's version number must be 1")
+    timestamp = uuid1.time
+    time_high_and_time_mid = timestamp >> 12
+    time_low_and_version = timestamp & 0x0FFF
+    uuid_int = time_high_and_time_mid << 80
+    uuid_int |= time_low_and_version << 64
+    uuid_int |= uuid1.clock_seq << 48
+    uuid_int |= uuid1.node
+    return UUID(int=uuid_int, version=6, is_safe=uuid1.is_safe)
+
+
 _last_v6_timestamp = None
 _last_v7_timestamp = None
 _last_v8_timestamp = None

test/test_uuid6.py

@@ -3,7 +3,7 @@
 from unittest.mock import patch
 from uuid import uuid1
 
-from uuid6 import UUID, uuid6, uuid7, uuid8
+from uuid6 import UUID, uuid6, uuid7, uuid8, uuid1_to_uuid6
 
 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}$"
@@ -39,6 +39,19 @@ def test_uuid8_generation(self):
             self.assertLess(uuid8_1, uuid8_2)
             uuid8_1 = uuid8_2
 
+    def test_uuid1_to_uuid6_generation(self):
+        uuid6_1 = None
+        for _ in range(1000):
+            uuid_1 = uuid1()
+            uuid6_2 = uuid1_to_uuid6(uuid_1)
+            self.assertEqual(uuid6_2.version, 6)
+            self.assertEqual(uuid6_2.node, uuid_1.node)
+            self.assertEqual(uuid6_2.clock_seq, uuid_1.clock_seq)
+            self.assertEqual(uuid6_2.time, uuid_1.time)
+            if uuid6_1 is not None:
+                self.assertLess(uuid6_1, uuid6_2)
+            uuid6_1 = uuid6_2
+
     def test_invalid_int(self):
         with self.assertRaises(ValueError):
             _ = UUID(int=-1)
@@ -155,6 +168,10 @@ def test_multiple_arguments(self):
         with self.assertRaises(TypeError):
             _ = UUID(int=0, hex="061d0edc-bea0-75cc-9892-f6295fd7d295")
 
+    def test_convert_invalid_version(self):
+        with self.assertRaises(ValueError):
+            _ = uuid1_to_uuid6(uuid7())
+
 
 if __name__ == "__main__":
     unittest.main()

test/test_vectors.py

@@ -10,7 +10,7 @@
 import unittest
 from unittest.mock import patch
 
-from uuid6 import UUID, uuid6, uuid7, uuid8
+from uuid6 import UUID, uuid6, uuid7, uuid8, uuid1_to_uuid6
 
 
 class TestVectors6(unittest.TestCase):
@@ -56,6 +56,11 @@ def test_uuid6_time_from_hex(self):
         uuid_1 = UUID(hex="C232AB00-9414-11EC-B3C8-9E6BDECED846")
         self.assertEqual(uuid_6.time, uuid_1.time)
 
+    def test_uuid1_to_uuid6(self):
+        uuid_1 = UUID(hex="C232AB00-9414-11EC-B3C8-9E6BDECED846")
+        uuid_6 = uuid1_to_uuid6(uuid_1)
+        self.assertEqual(str(uuid_6), "1ec9414c-232a-6b00-b3c8-9e6bdeced846")
+
 
 class TestVectors7(unittest.TestCase):
     """