Coverage for python / lsst / daf / butler / _uuid.py: 42%

1# This file is part of daf_butler. 

2# 

3# Developed for the LSST Data Management System. 

4# This product includes software developed by the LSST Project 

5# (http://www.lsst.org). 

6# See the COPYRIGHT file at the top-level directory of this distribution 

7# for details of code ownership. 

8# 

9# This software is dual licensed under the GNU General Public License and also 

10# under a 3-clause BSD license. Recipients may choose which of these licenses 

11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt, 

12# respectively. If you choose the GPL option then the following text applies 

13# (but note that there is still no warranty even if you opt for BSD instead): 

14# 

15# This program is free software: you can redistribute it and/or modify 

16# it under the terms of the GNU General Public License as published by 

17# the Free Software Foundation, either version 3 of the License, or 

18# (at your option) any later version. 

19# 

20# This program is distributed in the hope that it will be useful, 

21# but WITHOUT ANY WARRANTY; without even the implied warranty of 

22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

23# GNU General Public License for more details. 

24# 

25# You should have received a copy of the GNU General Public License 

26# along with this program. If not, see <http://www.gnu.org/licenses/>. 

27 

28from __future__ import annotations 

29 

30__all__ = ("generate_uuidv7",) 

31 

32import time 

33from uuid import UUID, uuid4 

34 

35 

36def generate_uuidv7() -> UUID: 

37 """Generate a v7 UUID compliant with IETF RFC-9562. 

38 

39 Returns 

40 ------- 

41 uuid : `uuid.UUID` 

42 Version 7 UUID. 

43 """ 

44 # Python 3.14 will include an implementation of UUIDv7 that can replace 

45 # this, but at the time of writing 3.14 hasn't been released and we're 

46 # still supporting 3.12. There are a few libraries on PyPI with an 

47 # implementation of v7 UUIDs, but none of them look well-maintained. 

48 # 

49 # This is the format of a v7 UUID: 

50 # 0 1 2 3 

51 # 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 

52 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

53 # | unix_ts_ms | 

54 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

55 # | unix_ts_ms | ver | rand_a | 

56 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

57 # |var| rand_b | 

58 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

59 # | rand_b | 

60 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 

61 # 

62 # It's basically identical to a UUID v4, but with the top 6 bytes 

63 # replaced with a millisecond UNIX timestamp. 

64 

65 # Generate a UUIDv4 for the random portion of the data. 

66 # A little wasteful, but means we inherit the best practices from 

67 # the standard library for generating this random data. 

68 byte_data = bytearray(uuid4().bytes) 

69 

70 # Replace high 6 bytes with millisecond UNIX timestamp. 

71 timestamp = time.time_ns() // 1_000_000 

72 timestamp_bytes = timestamp.to_bytes(length=6, byteorder="big") 

73 byte_data[0:6] = timestamp_bytes 

74 

75 # Set 4-bit version field to 7. 

76 byte_data[6] &= 0x0F 

77 byte_data[6] |= 0x70 

78 

79 return UUID(bytes=bytes(byte_data))