uuid – объекты UUID в соответствии с RFC 9562¶uuid – UUID objects according to 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, определяющий внутреннюю структуру 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-адреса предпочтительнее локально управляемых 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 не указан, используется getnode() для получения аппаратного адреса в виде 48-битного положительного целого числа. Когда порядковый номер 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, у которой все 128 бит установлены в ноль согласно RFC 9562, §5.9.

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

uuid.MAX¶

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

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

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

>>> import uuid

>>> # создать UUID на основе идентификатора хоста и текущего времени
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # создать UUID с использованием MD5-хеша UUID пространства имён и имени
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # создать случайный UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # создать UUID с использованием SHA-1-хеша UUID пространства имён и имени
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # создать UUID из строки шестнадцатеричных цифр (фигурные скобки и дефисы игнорируются)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')

>>> # преобразовать UUID в строку шестнадцатеричных цифр стандартного вида
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # получить сырые 16 байт UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # создать UUID из 16-байтовой строки
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # получить нулевой UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # получить максимальный UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

>>> # то же, что и UUIDv1, но с переупорядоченными полями для улучшения локальности в БД
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')

>>> # получить время создания UUIDv7 (локальное) в виде метки времени в миллисекундах
>>> u = uuid.uuid7()
>>> u.time
1743936859822

>>> # получить время создания UUIDv7 (локальное) в виде объекта datetime
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

>>> # создать UUID с пользовательскими блоками
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')

# сгенерировать случайный UUID – по умолчанию используется uuid4()
$ python -m uuid

# сгенерировать UUID с помощью uuid1()
$ python -m uuid -u uuid1

# сгенерировать UUID с помощью uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

# сгенерировать 42 случайных UUID
$ python -m uuid -C 42