> **Источник:** https://python-all.ru/3.16/library/uuid.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # `uuid` – объекты UUID в соответствии с [**RFC 9562**](https://python-all.ru/3.16/library/uuid.html) **Исходный код:** [Lib/uuid.py](https://python-all.ru/src/main/Lib/uuid.py) --- Этот модуль предоставляет неизменяемые [`UUID`](https://python-all.ru/3.16/library/uuid.html#uuid.UUID) объекты (класс `UUID`) и [функции](https://python-all.ru/3.16/library/uuid.html#uuid-factory-functions) для генерации UUID, соответствующих определённой версии UUID, как указано в [**RFC 9562**](https://python-all.ru/3.16/library/uuid.html) (который заменяет [**RFC 4122**](https://python-all.ru/3.16/library/uuid.html)), например [`uuid1()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid1) для UUID версии 1, [`uuid3()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid3) для UUID версии 3 и так далее. Обратите внимание, что UUID версии 2 намеренно опущен, так как он выходит за рамки RFC. Если вам нужен просто уникальный идентификатор, скорее всего, стоит вызвать [`uuid1()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid1) или [`uuid4()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid4). Обратите внимание, что `uuid1()` может нарушить конфиденциальность, так как создаёт UUID, содержащий сетевой адрес компьютера. `uuid4()` создаёт случайный UUID. В зависимости от поддержки базовой платформы, [`uuid1()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid1) может возвращать или не возвращать «безопасный» UUID. Безопасный UUID – это UUID, сгенерированный с использованием методов синхронизации, которые гарантируют, что никакие два процесса не смогут получить одинаковый UUID. Все экземпляры [`UUID`](https://python-all.ru/3.16/library/uuid.html#uuid.UUID) имеют атрибут [`is_safe`](https://python-all.ru/3.16/library/uuid.html#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: ```python 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**](https://python-all.ru/3.16/library/uuid.html), переопределяя биты в заданных *hex*, *bytes*, *bytes\_le*, *fields* или *int*. Сравнение объектов UUID осуществляется путём сравнения их атрибутов [`UUID.int`](https://python-all.ru/3.16/library/uuid.html#uuid.UUID.int). Сравнение с объектом, не являющимся UUID, вызывает исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). `str(uuid)` возвращает строку в формате `12345678-1234-5678-1234-567812345678`, где 32 шестнадцатеричные цифры представляют UUID. Экземпляры [`UUID`](https://python-all.ru/3.16/library/uuid.html#uuid.UUID) имеют следующие атрибуты только для чтения: #### `UUID.bytes` UUID в виде 16-байтовой строки (содержащей шесть целочисленных полей в порядке байтов от старшего к младшему). #### `UUID.bytes_le` UUID в виде 16-байтовой строки (с *time\_low*, *time\_mid* и *time\_hi\_version* в порядке байтов от младшего к старшему). #### `UUID.fields` Кортеж из шести целочисленных полей UUID, которые также доступны в виде шести отдельных атрибутов и двух производных атрибутов: | Поле | Значение | | --- | --- | | UUID.time\_low | Первые 32 бита UUID. Актуально только для версии 1. | | UUID.time\_mid | Следующие 16 бит UUID. Актуально только для версии 1. | | UUID.time\_hi\_version | Следующие 16 бит UUID. Актуально только для версии 1. | | UUID.clock\_seq\_hi\_variant | Следующие 8 бит UUID. Актуально только для версий 1 и 6. | | UUID.clock\_seq\_low | Следующие 8 бит UUID. Актуально только для версий 1 и 6. | | UUID.node | Последние 48 бит UUID. Актуально только для версии 1. | | UUID.time | 60-битная временная метка как количество 100-наносекундных интервалов с начала григорианской эпохи (1582-10-15 00:00:00) для версий 1 и 6, или 48-битная временная метка в миллисекундах с начала эпохи Unix (1970-01-01 00:00:00) для версии 7. | | UUID.clock\_seq | 14-битный номер последовательности. Актуально только для версий 1 и 6. | #### `UUID.hex` UUID в виде 32-символьной шестнадцатеричной строки в нижнем регистре. #### `UUID.int` UUID в виде 128-битного целого числа. #### `UUID.urn` UUID в виде URN, как указано в [**RFC 9562**](https://python-all.ru/3.16/library/uuid.html). #### `UUID.variant` Вариант UUID, определяющий внутреннюю структуру UUID. Это будет одна из констант [`RESERVED_NCS`](https://python-all.ru/3.16/library/uuid.html#uuid.RESERVED_NCS), [`RFC_4122`](https://python-all.ru/3.16/library/uuid.html#uuid.RFC_4122), [`RESERVED_MICROSOFT`](https://python-all.ru/3.16/library/uuid.html#uuid.RESERVED_MICROSOFT) или [`RESERVED_FUTURE`](https://python-all.ru/3.16/library/uuid.html#uuid.RESERVED_FUTURE). #### `UUID.version` Номер версии UUID (от 1 до 8, имеет смысл только если вариант [`RFC_4122`](https://python-all.ru/3.16/library/uuid.html#uuid.RFC_4122)). Изменено в версии 3.14: Добавлены UUID версий 6, 7 и 8. #### `UUID.is_safe` Перечисление [`SafeUUID`](https://python-all.ru/3.16/library/uuid.html#uuid.SafeUUID), указывающее, сгенерировала ли платформа UUID безопасным для многопроцессной работы способом. Добавлено в версии 3.7. Модуль `uuid` определяет следующие функции: #### `uuid.getnode()` Получает аппаратный адрес в виде 48-битного положительного целого числа. При первом запуске он может запустить отдельную программу, что может быть довольно медленно. Если все попытки получить аппаратный адрес не удались, выбирается случайное 48-битное число с установленным битом многоадресной передачи (наименее значимый бит первого октета) в 1, как рекомендовано в [**RFC 4122**](https://python-all.ru/3.16/library/uuid.html). «Аппаратный адрес» означает MAC-адрес сетевого интерфейса. На машине с несколькими сетевыми интерфейсами универсально управляемые MAC-адреса (т.е. где второй наименее значимый бит первого октета *сброшен*) будут предпочтительнее локально управляемых MAC-адресов, но без других гарантий порядка. Изменено в версии 3.7: Универсально управляемые MAC-адреса предпочтительнее локально управляемых MAC-адресов, поскольку первые гарантированно\\нглобально уникальны, а вторые – нет. #### `uuid.uuid1(node=None, clock_seq=None)` Генерирует UUID из идентификатора хоста, номера последовательности и текущего времени в соответствии с [**RFC 9562, §5.1**](https://python-all.ru/3.16/library/uuid.html). Когда *node* не указан, используется [`getnode()`](https://python-all.ru/3.16/library/uuid.html#uuid.getnode) для получения аппаратного адреса в виде 48-битного положительного целого числа. Когда порядковый номер *clock\_seq* не указан, генерируется псевдослучайное 14-битное положительное целое число. Если *node* или *clock\_seq* превышают ожидаемое количество бит, сохраняются только их наименее значимые биты. #### `uuid.uuid3(namespace, name)` Генерирует UUID на основе MD5-хэша идентификатора пространства имён (который является UUID) и имени (которое является объектом [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или строкой, закодированной в UTF-8) в соответствии с [**RFC 9562, §5.3**](https://python-all.ru/3.16/library/uuid.html). #### `uuid.uuid4()` Генерирует случайный UUID криптографически безопасным способом согласно [**RFC 9562, §5.4**](https://python-all.ru/3.16/library/uuid.html). #### `uuid.uuid5(namespace, name)` Генерирует UUID на основе SHA-1-хеша идентификатора пространства имён (UUID) и имени (объект [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или строка, которая будет закодирована в UTF-8) согласно [**RFC 9562, §5.5**](https://python-all.ru/3.16/library/uuid.html). #### `uuid.uuid6(node=None, clock_seq=None)` Генерирует UUID из порядкового номера и текущего времени согласно [**RFC 9562, §5.6**](https://python-all.ru/3.16/library/uuid.html). Это альтернатива [`uuid1()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid1) для улучшения локальности базы данных. Когда *node* не указан, используется [`getnode()`](https://python-all.ru/3.16/library/uuid.html#uuid.getnode) для получения аппаратного адреса в виде 48-битного положительного целого числа. Когда порядковый номер *clock\_seq* не указан, генерируется псевдослучайное 14-битное положительное целое число. Если *node* или *clock\_seq* превышают ожидаемое количество бит, сохраняются только их наименее значимые биты. Добавлено в версии 3.14. #### `uuid.uuid7()` Генерирует временной UUID согласно [**RFC 9562, §5.7**](https://python-all.ru/3.16/library/uuid.html). Для обеспечения переносимости между платформами, не поддерживающими точность ниже миллисекунды, UUID, создаваемые этой функцией, содержат 48-битную метку времени и 42-битный счётчик, гарантирующие монотонность в пределах одной миллисекунды. Добавлено в версии 3.14. #### `uuid.uuid8(a=None, b=None, c=None)` Генерирует псевдослучайный UUID согласно [**RFC 9562, §5.8**](https://python-all.ru/3.16/library/uuid.html). Если указаны, параметры *a*, *b* и *c* должны быть положительными целыми числами размером 48, 12 и 62 бит соответственно. Если они превышают ожидаемое количество бит, сохраняются только их наименее значимые биты; неуказанные аргументы заменяются псевдослучайным целым числом соответствующего размера. По умолчанию *a*, *b* и *c* не генерируются криптографически безопасным генератором псевдослучайных чисел (CSPRNG). Используйте [`uuid4()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid4), когда UUID требуется использовать в контексте, связанном с безопасностью. Добавлено в версии 3.14. Модуль `uuid` определяет следующие идентификаторы пространств имён для использования с [`uuid3()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid3) или [`uuid5()`](https://python-all.ru/3.16/library/uuid.html#uuid.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`](https://python-all.ru/3.16/library/uuid.html#uuid.UUID.variant): #### `uuid.RESERVED_NCS` Зарезервировано для совместимости с NCS. #### `uuid.RFC_4122` Определяет структуру UUID, приведённую в [**RFC 4122**](https://python-all.ru/3.16/library/uuid.html). Эта константа сохранена для обратной совместимости, несмотря на то, что [**RFC 4122**](https://python-all.ru/3.16/library/uuid.html) заменён на [**RFC 9562**](https://python-all.ru/3.16/library/uuid.html). #### `uuid.RESERVED_MICROSOFT` Зарезервировано для совместимости с Microsoft. #### `uuid.RESERVED_FUTURE` Зарезервировано для будущего определения. Модуль `uuid` определяет специальные значения UUID Nil и Max: #### `uuid.NIL` Особая форма UUID, у которой все 128 бит установлены в ноль согласно [**RFC 9562, §5.9**](https://python-all.ru/3.16/library/uuid.html). Добавлено в версии 3.14. #### `uuid.MAX` Особая форма UUID, у которой все 128 бит установлены в единицу согласно [**RFC 9562, §5.10**](https://python-all.ru/3.16/library/uuid.html). Добавлено в версии 3.14. > **См. также** > > **[**RFC 9562**](https://python-all.ru/3.16/library/uuid.html) – пространство имён URN универсального уникального идентификатора (UUID)** > > Данная спецификация определяет пространство имён универсальных имён ресурсов (URN) для UUID, их внутренний формат, а также методы генерации UUID. ## Использование командной строки Добавлено в версии 3.12. Модуль `uuid` можно запускать как скрипт из командной строки. ```sh python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME] ``` Принимаются следующие опции: #### `-h, --help` Показать справку и выйти. #### `-u ` #### `--uuid ` Укажите имя функции, используемой для генерации uuid. По умолчанию [`uuid4()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid4) используется. Изменено в версии 3.14: Разрешена генерация UUID версий 6, 7 и 8. #### `-n ` #### `--namespace ` Пространство имён – это `UUID` или `@ns`, где `ns` – это известный предопределённый UUID, адресуемый по имени пространства имён. Например, `@dns`, `@url`, `@oid` и `@x500`. Требуется только для функций [`uuid3()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid3) / [`uuid5()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid5). #### `-N ` #### `--name ` Имя, используемое как часть генерации uuid. Требуется только для функций [`uuid3()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid3) / [`uuid5()`](https://python-all.ru/3.16/library/uuid.html#uuid.uuid5). #### `-C ` #### `--count ` Сгенерировать *num* новых UUID. Добавлено в версии 3.14. ## Пример Вот несколько примеров типичного использования модуля `uuid`: ```python >>> 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`: ```shell # сгенерировать случайный 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 ```