uuid — объекты UUID согласно RFC 9562

Исходный код: Lib/uuid.py

Этот модуль предоставляет неизменяемые объекты UUID (класс UUID) и функции для генерации UUID, соответствующих определённой версии UUID, указанной в RFC 9562 (который заменяет RFC 4122), например, uuid1() для UUID версии 1, uuid3() для UUID версии 3 и так далее. Обратите внимание, что UUID версии 2 намеренно не рассматривается, поскольку он выходит за рамки RFC.

Если вам нужен только уникальный идентификатор, вероятно, следует вызвать uuid1() или uuid4(). Обратите внимание, что uuid1() может поставить под угрозу конфиденциальность, поскольку создаёт UUID, содержащий сетевой адрес компьютера. uuid4() создаёт случайный UUID.

В зависимости от поддержки со стороны базовой платформы uuid1() может возвращать или не возвращать «безопасный» UUID. Безопасный UUID — это UUID, сгенерированный с использованием методов синхронизации, которые гарантируют, что два процесса не смогут получить одинаковый UUID. Все экземпляры UUID имеют атрибут is_safe, который сообщает сведения о безопасности UUID с помощью следующего перечисления:

class uuid.SafeUUID

Добавлено в версии 3.7.

safe

UUID сгенерирован платформой безопасным для многопроцессной обработки способом.

unsafe

UUID сгенерирован небезопасным для многопроцессной обработки способом.

unknown

Платформа не предоставляет сведений о том, был ли UUID сгенерирован безопасно.

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

Создаёт UUID из строки, состоящей из 32 шестнадцатеричных цифр; строки из 16 байтов в порядке от старшего к младшему в аргументе bytes; строки из 16 байтов в порядке от младшего к старшему в аргументе bytes_le; кортежа из шести целых чисел (32-битное time_low, 16-битное time_mid, 16-битное time_hi_version, 8-битное clock_seq_hi_variant, 8-битное clock_seq_low, 48-битное node) в аргументе fields или одного 128-битного целого числа в аргументе int. Если передана строка шестнадцатеричных цифр, фигурные скобки, дефисы и префикс URN необязательны. Например, все эти выражения возвращают один и тот же UUID:

UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes=b'\x12\x34\x56\x78'*4)
UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' +
              b'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)

Необходимо указать ровно один из аргументов: hex, bytes, bytes_le, fields или int. Аргумент version необязателен; если он указан, вариант и номер версии результирующего UUID будут установлены в соответствии с RFC 9562, переопределяя биты в переданном hex, bytes, bytes_le, fields или int.

Объекты UUID сравниваются путём сравнения их атрибутов UUID.int. Сравнение с объектом, не являющимся UUID, вызывает исключение TypeError.

str(uuid) возвращает строку вида 12345678-1234-5678-1234-567812345678, где 32 шестнадцатеричные цифры представляют UUID.

Экземпляры UUID имеют следующие атрибуты, доступные только для чтения:

UUID.bytes

UUID в виде строки из 16 байтов (содержащей шесть целочисленных полей в порядке байтов от старшего к младшему).

UUID.bytes_le

UUID в виде строки из 16 байтов (где time_low, time_mid и time_hi_version представлены в порядке байтов от младшего к старшему).

UUID.fields

Кортеж из шести целочисленных полей UUID, которые также доступны как шесть отдельных атрибутов и два производных атрибута:

UUID.hex

UUID в виде 32-символьной строки строчных шестнадцатеричных цифр.

UUID.int

UUID в виде 128-битного целого числа.

UUID.urn

UUID в виде URN согласно RFC 9562.

UUID.variant

Вариант UUID, определяющий его внутреннюю структуру. Это будет одна из констант RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT или RESERVED_FUTURE.

UUID.version

Номер версии UUID (от 1 до 8; имеет смысл только тогда, когда вариант — RFC_4122).

Изменено в версии 3.14: Добавлены версии UUID 6, 7 и 8.

UUID.is_safe

Элемент перечисления SafeUUID, указывающий, сгенерировала ли платформа UUID безопасным для многопроцессной обработки способом.

Добавлено в версии 3.7.

Модуль uuid определяет следующие функции:

uuid.getnode()

Получить аппаратный адрес в виде положительного 48-битного целого числа. При первом вызове функция может запустить отдельную программу, что может занять довольно много времени. Если все попытки получить аппаратный адрес завершатся неудачей, будет выбрано случайное 48-битное число, у которого бит групповой передачи (наименее значимый бит первого октета) установлен в 1, как рекомендуется в RFC 4122. Под «аппаратным адресом» подразумевается MAC-адрес сетевого интерфейса. На компьютере с несколькими сетевыми интерфейсами предпочтение отдаётся глобально администрируемым MAC-адресам (то есть адресам, у которых второй наименее значимый бит первого октета не установлен), а не локально администрируемым MAC-адресам; других гарантий порядка нет.

Изменено в версии 3.7: Глобально администрируемые MAC-адреса предпочтительнее локально администрируемых, поскольку первые гарантированно уникальны во всём мире, а последние — нет.

uuid.uuid1(node=None, clock_seq=None)

Сгенерировать UUID на основе идентификатора узла, номера последовательности и текущего времени согласно RFC 9562, §5.1.

Если node не указан, для получения аппаратного адреса в виде положительного 48-битного целого числа используется getnode(). Если номер последовательности clock_seq не указан, генерируется псевдослучайное положительное 14-битное целое число.

Если node или clock_seq превышает ожидаемое количество битов, сохраняются только наименее значимые биты.

uuid.uuid3(namespace, name)

Сгенерировать UUID на основе хеша MD5 от идентификатора пространства имён (который является UUID) и имени (которое является объектом bytes или строкой, кодируемой с помощью UTF-8) согласно RFC 9562, §5.3.

uuid.uuid4()

Сгенерировать случайный UUID криптографически безопасным способом согласно RFC 9562, §5.4.

uuid.uuid5(namespace, name)

Сгенерировать UUID на основе хеша SHA-1 от идентификатора пространства имён (который является UUID) и имени (которое является объектом bytes или строкой, кодируемой с помощью UTF-8) согласно RFC 9562, §5.5.

uuid.uuid6(node=None, clock_seq=None)

Сгенерировать UUID на основе номера последовательности и текущего времени согласно RFC 9562, §5.6.

Это альтернатива uuid1(), повышающая локальность базы данных.

Если node не указан, для получения аппаратного адреса в виде положительного 48-битного целого числа используется getnode(). Если номер последовательности clock_seq не указан, генерируется псевдослучайное положительное 14-битное целое число.

Если node или clock_seq превышает ожидаемое количество битов, сохраняются только наименее значимые биты.

Добавлено в версии 3.14.

uuid.uuid7()

Сгенерировать UUID на основе времени согласно RFC 9562, §5.7.

Для обеспечения переносимости на платформах, не поддерживающих субмиллисекундную точность, UUID, создаваемые этой функцией, содержат 48-битную временную метку и используют 42-битный счётчик для гарантии монотонности в пределах одной миллисекунды.

Добавлено в версии 3.14.

uuid.uuid8(a=None, b=None, c=None)

Сгенерировать псевдослучайный UUID согласно RFC 9562, §5.8.

Если параметры a, b и c указаны, они должны быть положительными целыми числами размером соответственно 48, 12 и 62 бита. Если они превышают ожидаемое количество битов, сохраняются только наименее значимые биты; для неуказанных аргументов подставляется псевдослучайное целое число соответствующего размера.

По умолчанию для генерации a, b и c не используется криптографически стойкий генератор псевдослучайных чисел (CSPRNG). Используйте uuid4(), если UUID нужен в контексте, чувствительном к безопасности.

Добавлено в версии 3.14.

Модуль uuid определяет следующие идентификаторы пространства имён для использования с uuid3() или uuid5().

uuid.NAMESPACE_DNS

При указании этого пространства имён строка name является полным доменным именем.

uuid.NAMESPACE_URL

При указании этого пространства имён строка name является URL.

uuid.NAMESPACE_OID

При указании этого пространства имён строка name является ISO OID.

uuid.NAMESPACE_X500

При указании этого пространства имён строка name является X.500 DN в DER или в текстовом формате вывода.

Модуль uuid определяет следующие константы для возможных значений атрибута variant:

uuid.RESERVED_NCS

Зарезервировано для совместимости с NCS.

uuid.RFC_4122

Указывает структуру UUID, заданную в RFC 4122. Эта константа сохранена для обратной совместимости, хотя RFC 4122 был заменён на RFC 9562.

uuid.RESERVED_MICROSOFT

Зарезервировано для совместимости с Microsoft.

uuid.RESERVED_FUTURE

Зарезервировано для будущего определения.

Модуль uuid определяет специальные значения UUID Nil и Max:

uuid.NIL

Специальная форма UUID, для которой согласно RFC 9562, §5.9 все 128 бит установлены в ноль.

Добавлено в версии 3.14.

uuid.MAX

Специальная форма UUID, для которой согласно RFC 9562, §5.10 все 128 бит установлены в единицу.

Добавлено в версии 3.14.

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]

>>> import uuid

>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')

>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

>>> # same as UUIDv1 but with fields reordered to improve DB locality
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')

>>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
>>> u = uuid.uuid7()
>>> u.time
1743936859822

>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

>>> # make a UUID with custom blocks
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')

# generate a random UUID - by default uuid4() is used
$ python -m uuid

# generate a UUID using uuid1()
$ python -m uuid -u uuid1

# generate a UUID using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

# generate 42 random UUIDs
$ python -m uuid -C 42