`uuid.md`

349 строк · 24.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/library/uuid.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `uuid` – объекты UUID в соответствии с [**RFC 9562**](https://python-all.ru/3/library/uuid.html)89**Исходный код:** [Lib/uuid.py](https://python-all.ru/src/3.14/Lib/uuid.py)1011---1213Этот модуль предоставляет неизменяемые [`UUID`](https://python-all.ru/3/library/uuid.html#uuid.UUID) объекты (класс `UUID`) и [функции](https://python-all.ru/3/library/uuid.html#uuid-factory-functions) для генерации UUID, соответствующих определённой версии UUID, как указано в [**RFC 9562**](https://python-all.ru/3/library/uuid.html) (который заменяет [**RFC 4122**](https://python-all.ru/3/library/uuid.html)), например [`uuid1()`](https://python-all.ru/3/library/uuid.html#uuid.uuid1) для UUID версии 1, [`uuid3()`](https://python-all.ru/3/library/uuid.html#uuid.uuid3) для UUID версии 3 и так далее. Обратите внимание, что UUID версии 2 намеренно опущен, так как он выходит за рамки RFC.1415Если вам нужен просто уникальный идентификатор, скорее всего, стоит вызвать [`uuid1()`](https://python-all.ru/3/library/uuid.html#uuid.uuid1) или [`uuid4()`](https://python-all.ru/3/library/uuid.html#uuid.uuid4). Обратите внимание, что `uuid1()` может нарушить конфиденциальность, так как создаёт UUID, содержащий сетевой адрес компьютера. `uuid4()` создаёт случайный UUID.1617В зависимости от поддержки базовой платформы, [`uuid1()`](https://python-all.ru/3/library/uuid.html#uuid.uuid1) может возвращать или не возвращать «безопасный» UUID. Безопасный UUID – это UUID, сгенерированный с использованием методов синхронизации, которые гарантируют, что никакие два процесса не смогут получить одинаковый UUID. Все экземпляры [`UUID`](https://python-all.ru/3/library/uuid.html#uuid.UUID) имеют атрибут [`is_safe`](https://python-all.ru/3/library/uuid.html#uuid.UUID.is_safe), который передаёт любую информацию о безопасности UUID, используя это перечисление:1819#### `class uuid.SafeUUID`2021Добавлено в версии 3.7.2223#### `safe`2425UUID был сгенерирован платформой способом, безопасным для многопроцессорной работы.2627#### `unsafe`2829UUID не был сгенерирован способом, безопасным для многопроцессорной работы.3031#### `unknown`3233Платформа не предоставляет информацию о том, был ли UUID сгенерирован безопасно или нет.3435#### `class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)`3637Создаёт 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:3839```python40UUID('{12345678-1234-5678-1234-567812345678}')41UUID('12345678123456781234567812345678')42UUID('urn:uuid:12345678-1234-5678-1234-567812345678')43UUID(bytes=b'\x12\x34\x56\x78'*4)44UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' +45              b'\x12\x34\x56\x78\x12\x34\x56\x78')46UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))47UUID(int=0x12345678123456781234567812345678)48```4950Должен быть указан ровно один из *hex*, *bytes*, *bytes\_le*, *fields* или *int*. Аргумент *version* является необязательным; если он задан, результирующий UUID будет иметь вариант и номер версии, установленные в соответствии с [**RFC 9562**](https://python-all.ru/3/library/uuid.html), переопределяя биты в заданных *hex*, *bytes*, *bytes\_le*, *fields* или *int*.5152Сравнение объектов UUID осуществляется путём сравнения их атрибутов [`UUID.int`](https://python-all.ru/3/library/uuid.html#uuid.UUID.int). Сравнение с объектом, не являющимся UUID, вызывает исключение [`TypeError`](https://python-all.ru/3/library/exceptions.html#TypeError).5354`str(uuid)` возвращает строку в формате `12345678-1234-5678-1234-567812345678`, где 32 шестнадцатеричные цифры представляют UUID.5556Экземпляры [`UUID`](https://python-all.ru/3/library/uuid.html#uuid.UUID) имеют следующие атрибуты только для чтения:5758#### `UUID.bytes`5960UUID в виде 16-байтовой строки (содержащей шесть целочисленных полей в порядке байтов от старшего к младшему).6162#### `UUID.bytes_le`6364UUID в виде 16-байтовой строки (с *time\_low*, *time\_mid* и *time\_hi\_version* в порядке байтов от младшего к старшему).6566#### `UUID.fields`6768Кортеж из шести целочисленных полей UUID, которые также доступны в виде шести отдельных атрибутов и двух производных атрибутов:6970| Поле | Значение |71| --- | --- |72| UUID.time\_low | Первые 32 бита UUID. Актуально только для версии 1. |73| UUID.time\_mid | Следующие 16 бит UUID. Актуально только для версии 1. |74| UUID.time\_hi\_version | Следующие 16 бит UUID. Актуально только для версии 1. |75| UUID.clock\_seq\_hi\_variant | Следующие 8 бит UUID. Актуально только для версий 1 и 6. |76| UUID.clock\_seq\_low | Следующие 8 бит UUID. Актуально только для версий 1 и 6. |77| UUID.node | Последние 48 бит UUID. Актуально только для версии 1. |78| UUID.time | 60-битная временная метка как количество 100-наносекундных интервалов с начала григорианской эпохи (1582-10-15 00:00:00) для версий 1 и 6, или 48-битная временная метка в миллисекундах с начала эпохи Unix (1970-01-01 00:00:00) для версии 7. |79| UUID.clock\_seq | 14-битный номер последовательности. Актуально только для версий 1 и 6. |8081#### `UUID.hex`8283UUID в виде 32-символьной шестнадцатеричной строки в нижнем регистре.8485#### `UUID.int`8687UUID в виде 128-битного целого числа.8889#### `UUID.urn`9091UUID в виде URN, как указано в [**RFC 9562**](https://python-all.ru/3/library/uuid.html).9293#### `UUID.variant`9495Вариант UUID, определяющий внутреннюю структуру UUID. Это будет одна из констант [`RESERVED_NCS`](https://python-all.ru/3/library/uuid.html#uuid.RESERVED_NCS), [`RFC_4122`](https://python-all.ru/3/library/uuid.html#uuid.RFC_4122), [`RESERVED_MICROSOFT`](https://python-all.ru/3/library/uuid.html#uuid.RESERVED_MICROSOFT) или [`RESERVED_FUTURE`](https://python-all.ru/3/library/uuid.html#uuid.RESERVED_FUTURE).9697#### `UUID.version`9899Номер версии UUID (от 1 до 8, имеет смысл только если вариант [`RFC_4122`](https://python-all.ru/3/library/uuid.html#uuid.RFC_4122)).100101Изменено в версии 3.14: Добавлены UUID версий 6, 7 и 8.102103#### `UUID.is_safe`104105Перечисление [`SafeUUID`](https://python-all.ru/3/library/uuid.html#uuid.SafeUUID), указывающее, сгенерировала ли платформа UUID безопасным для многопроцессной работы способом.106107Добавлено в версии 3.7.108109Модуль `uuid` определяет следующие функции:110111#### `uuid.getnode()`112113Получает аппаратный адрес в виде 48-битного положительного целого числа. При первом запуске он может запустить отдельную программу, что может быть довольно медленно. Если все попытки получить аппаратный адрес не удались, выбирается случайное 48-битное число с установленным битом многоадресной передачи (наименее значимый бит первого октета) в 1, как рекомендовано в [**RFC 4122**](https://python-all.ru/3/library/uuid.html). «Аппаратный адрес» означает MAC-адрес сетевого интерфейса. На машине с несколькими сетевыми интерфейсами универсально управляемые MAC-адреса (т.е. где второй наименее значимый бит первого октета *сброшен*) будут предпочтительнее локально управляемых MAC-адресов, но без других гарантий порядка.114115Изменено в версии 3.7: Универсально управляемые MAC-адреса предпочтительнее локально управляемых MAC-адресов, поскольку первые гарантированно\\нглобально уникальны, а вторые – нет.116117#### `uuid.uuid1(node=None, clock_seq=None)`118119Генерирует UUID из идентификатора хоста, номера последовательности и текущего времени в соответствии с [**RFC 9562, §5.1**](https://python-all.ru/3/library/uuid.html).120121Если *node* не указан, для получения аппаратного адреса в виде 48-битного положительного целого числа используется [`getnode()`](https://python-all.ru/3/library/uuid.html#uuid.getnode). Если номер последовательности *clock\_seq* не указан, генерируется псевдослучайное 14-битное положительное целое число.122123Если *node* или *clock\_seq* превышают ожидаемое количество бит, сохраняются только их наименее значимые биты.124125#### `uuid.uuid3(namespace, name)`126127Генерирует UUID на основе MD5-хэша идентификатора пространства имён (который является UUID) и имени (которое является объектом [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes) или строкой, закодированной в UTF-8) в соответствии с [**RFC 9562, §5.3**](https://python-all.ru/3/library/uuid.html).128129#### `uuid.uuid4()`130131Генерирует случайный UUID криптографически безопасным способом согласно [**RFC 9562, §5.4**](https://python-all.ru/3/library/uuid.html).132133#### `uuid.uuid5(namespace, name)`134135Генерирует UUID на основе SHA-1-хеша идентификатора пространства имён (UUID) и имени (объект [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes) или строка, которая будет закодирована в UTF-8) согласно [**RFC 9562, §5.5**](https://python-all.ru/3/library/uuid.html).136137#### `uuid.uuid6(node=None, clock_seq=None)`138139Генерирует UUID из порядкового номера и текущего времени согласно [**RFC 9562, §5.6**](https://python-all.ru/3/library/uuid.html).140141Это альтернатива [`uuid1()`](https://python-all.ru/3/library/uuid.html#uuid.uuid1) для улучшения локальности базы данных.142143Когда *node* не указан, используется [`getnode()`](https://python-all.ru/3/library/uuid.html#uuid.getnode) для получения аппаратного адреса в виде 48-битного положительного целого числа. Когда порядковый номер *clock\_seq* не указан, генерируется псевдослучайное 14-битное положительное целое число.144145Если *node* или *clock\_seq* превышают ожидаемое количество бит, сохраняются только их наименее значимые биты.146147Добавлено в версии 3.14.148149#### `uuid.uuid7()`150151Генерирует временной UUID согласно [**RFC 9562, §5.7**](https://python-all.ru/3/library/uuid.html).152153Для обеспечения переносимости между платформами, не поддерживающими точность ниже миллисекунды, UUID, создаваемые этой функцией, содержат 48-битную метку времени и 42-битный счётчик, гарантирующие монотонность в пределах одной миллисекунды.154155Добавлено в версии 3.14.156157#### `uuid.uuid8(a=None, b=None, c=None)`158159Генерирует псевдослучайный UUID согласно [**RFC 9562, §5.8**](https://python-all.ru/3/library/uuid.html).160161Если указаны, параметры *a*, *b* и *c* должны быть положительными целыми числами размером 48, 12 и 62 бит соответственно. Если они превышают ожидаемое количество бит, сохраняются только их наименее значимые биты; неуказанные аргументы заменяются псевдослучайным целым числом соответствующего размера.162163По умолчанию *a*, *b* и *c* не генерируются криптографически безопасным генератором псевдослучайных чисел (CSPRNG). Используйте [`uuid4()`](https://python-all.ru/3/library/uuid.html#uuid.uuid4), когда UUID требуется использовать в контексте, связанном с безопасностью.164165Добавлено в версии 3.14.166167Модуль `uuid` определяет следующие идентификаторы пространств имён для использования с [`uuid3()`](https://python-all.ru/3/library/uuid.html#uuid.uuid3) или [`uuid5()`](https://python-all.ru/3/library/uuid.html#uuid.uuid5).168169#### `uuid.NAMESPACE_DNS`170171Если указано это пространство имён, строка *name* является полным доменным именем.172173#### `uuid.NAMESPACE_URL`174175Если указано это пространство имён, строка *name* является URL.176177#### `uuid.NAMESPACE_OID`178179Если указано это пространство имён, строка *name* является ISO OID.180181#### `uuid.NAMESPACE_X500`182183Если указано это пространство имён, строка *name* является X.500 DN в формате DER или текстовом формате вывода.184185Модуль `uuid` определяет следующие константы для возможных значений атрибута [`variant`](https://python-all.ru/3/library/uuid.html#uuid.UUID.variant):186187#### `uuid.RESERVED_NCS`188189Зарезервировано для совместимости с NCS.190191#### `uuid.RFC_4122`192193Определяет структуру UUID, приведённую в [**RFC 4122**](https://python-all.ru/3/library/uuid.html). Эта константа сохранена для обратной совместимости, несмотря на то, что [**RFC 4122**](https://python-all.ru/3/library/uuid.html) заменён на [**RFC 9562**](https://python-all.ru/3/library/uuid.html).194195#### `uuid.RESERVED_MICROSOFT`196197Зарезервировано для совместимости с Microsoft.198199#### `uuid.RESERVED_FUTURE`200201Зарезервировано для будущего определения.202203Модуль `uuid` определяет специальные значения UUID Nil и Max:204205#### `uuid.NIL`206207Особая форма UUID, у которой все 128 бит установлены в ноль согласно [**RFC 9562, §5.9**](https://python-all.ru/3/library/uuid.html).208209Добавлено в версии 3.14.210211#### `uuid.MAX`212213Особая форма UUID, у которой все 128 бит установлены в единицу согласно [**RFC 9562, §5.10**](https://python-all.ru/3/library/uuid.html).214215Добавлено в версии 3.14.216217> **См. также**218>219> **[**RFC 9562**](https://python-all.ru/3/library/uuid.html) – пространство имён URN универсального уникального идентификатора (UUID)**220>221> Данная спецификация определяет пространство имён универсальных имён ресурсов (URN) для UUID, их внутренний формат, а также методы генерации UUID.222223## Использование командной строки224225Добавлено в версии 3.12.226227Модуль `uuid` можно запускать как скрипт из командной строки.228229```sh230python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]231```232233Принимаются следующие опции:234235#### `-h, --help`236237Показать справку и выйти.238239#### `-u <uuid>`240241#### `--uuid <uuid>`242243Укажите имя функции, используемой для генерации uuid. По умолчанию [`uuid4()`](https://python-all.ru/3/library/uuid.html#uuid.uuid4) используется.244245Изменено в версии 3.14: Разрешена генерация UUID версий 6, 7 и 8.246247#### `-n <namespace>`248249#### `--namespace <namespace>`250251Пространство имён – это `UUID` или `@ns`, где `ns` – это известный предопределённый UUID, адресуемый по имени пространства имён. Например, `@dns`, `@url`, `@oid` и `@x500`. Требуется только для функций [`uuid3()`](https://python-all.ru/3/library/uuid.html#uuid.uuid3) / [`uuid5()`](https://python-all.ru/3/library/uuid.html#uuid.uuid5).252253#### `-N <name>`254255#### `--name <name>`256257Имя, используемое как часть генерации uuid. Требуется только для функций [`uuid3()`](https://python-all.ru/3/library/uuid.html#uuid.uuid3) / [`uuid5()`](https://python-all.ru/3/library/uuid.html#uuid.uuid5).258259#### `-C <num>`260261#### `--count <num>`262263Сгенерировать *num* новых UUID.264265Добавлено в версии 3.14.266267## Пример268269Вот несколько примеров типичного использования модуля `uuid`:270271```python272>>> import uuid273274>>> # создать UUID на основе идентификатора хоста и текущего времени275>>> uuid.uuid1()276UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')277278>>> # создать UUID с использованием MD5-хеша UUID пространства имён и имени279>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')280UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')281282>>> # создать случайный UUID283>>> uuid.uuid4()284UUID('16fd2706-8baf-433b-82eb-8c7fada847da')285286>>> # создать UUID с использованием SHA-1-хеша UUID пространства имён и имени287>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')288UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')289290>>> # создать UUID из строки шестнадцатеричных цифр (фигурные скобки и дефисы игнорируются)291>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')292293>>> # преобразовать UUID в строку шестнадцатеричных цифр стандартного вида294>>> str(x)295'00010203-0405-0607-0809-0a0b0c0d0e0f'296297>>> # получить сырые 16 байт UUID298>>> x.bytes299b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'300301>>> # создать UUID из 16-байтовой строки302>>> uuid.UUID(bytes=x.bytes)303UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')304305>>> # получить нулевой UUID306>>> uuid.NIL307UUID('00000000-0000-0000-0000-000000000000')308309>>> # получить максимальный UUID310>>> uuid.MAX311UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')312313>>> # то же, что и UUIDv1, но с переупорядоченными полями для улучшения локальности в БД314>>> uuid.uuid6()315UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')316317>>> # получить время создания UUIDv7 (локальное) в виде метки времени в миллисекундах318>>> u = uuid.uuid7()319>>> u.time3201743936859822321322>>> # получить время создания UUIDv7 (локальное) в виде объекта datetime323>>> import datetime as dt324>>> dt.datetime.fromtimestamp(u.time / 1000)325datetime.datetime(...)326327>>> # создать UUID с пользовательскими блоками328>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)329UUID('00001234-5678-8ef0-8000-000011223344')330```331332## Пример использования командной строки333334Ниже приведены несколько примеров типичного использования интерфейса командной строки `uuid`:335336```shell337# сгенерировать случайный UUID – по умолчанию используется uuid4()338$ python -m uuid339340# сгенерировать UUID с помощью uuid1()341$ python -m uuid -u uuid1342343# сгенерировать UUID с помощью uuid5344$ python -m uuid -u uuid5 -n @url -N example.com345346# сгенерировать 42 случайных UUID347$ python -m uuid -C 42348```349