`uuid` — Objetos UUID conforme RFC 9562¶

Código-fonte: Lib/uuid.py

Este módulo fornece objetos UUID imutáveis (a classe UUID) e funções para gerar UUIDs correspondentes a uma versão específica de UUID, conforme especificado em RFC 9562 (que substitui RFC 4122), por exemplo, uuid1() para a versão 1 de UUID, uuid3() para a versão 3 de UUID e assim por diante. Observe que a versão 2 de UUID foi omitida deliberadamente, pois está fora do escopo da RFC.

Se tudo o que você quer é um ID único, você provavelmente deve chamar uuid1() ou uuid4(). Note que uuid1() pode comprometer a privacidade, pois cria um UUID contendo o endereço de rede do computador. uuid4() cria um UUID aleatório.

Dependendo do suporte da plataforma subjacente, uuid1() pode ou não retornar um UUID “seguro”. Um UUID seguro é aquele que é gerado usando métodos de sincronização que garantem que dois processos não possam obter o mesmo UUID. Todas as instâncias de UUID têm um atributo is_safe que retransmite qualquer informação sobre a segurança do UUID, usando esta enumeração:

class uuid.SafeUUID¶

Adicionado na versão 3.7.

safe¶: O UUID foi gerado pela plataforma de forma segura para multiprocessamento.

unsafe¶: O UUID não foi gerado de forma segura para multiprocessamento.

unknown¶: A plataforma não fornece informações sobre se o UUID foi gerado com segurança ou não.

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

Cria um UUID a partir de uma sequência de 32 dígitos hexadecimais, uma sequência de 16 bytes em ordem big-endian como o argumento bytes, uma sequência de 16 bytes em ordem little-endian como o argumento bytes_le, uma tupla de seis inteiros (time_low de 32 bits, time_mid de 16 bits, time_hi_version de 16 bits, clock_seq_hi_variant de 8 bits, clock_seq_low de 8 bits, node de 48 bits) como o argumento fields ou um único inteiro de 128 bits como o argumento int. Quando uma sequência de dígitos hexadecimais é fornecida, chaves, hifens e um prefixo URN são todos opcionais. Por exemplo, todas essas expressões produzem o mesmo 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)

Exatamente um de hex, bytes, bytes_le, fields ou int deve ser fornecido. O argumento version é opcional; se fornecido, o UUID resultante terá sua variante e número de versão definidos de acordo com RFC 9562, substituindo bits no hex, bytes, bytes_le, fields ou int fornecido.

A comparação de objetos UUID é feita por meio da comparação de seus atributos UUID.int. A comparação com um objeto não UUID levanta uma TypeError.

str(uuid) retorna uma string no formato 12345678-1234-5678-1234-567812345678 onde os 32 dígitos hexadecimais representam o UUID.

As instâncias UUID têm estes atributos de somente leitura:

UUID.bytes¶: O UUID como uma string de 16 bytes (contendo os seis campos inteiros em ordem de bytes big-endian).

UUID.bytes_le¶: O UUID como uma string de 16 bytes (com time_low, time_mid e time_hi_version em ordem de bytes little-endian).

UUID.fields¶: Uma tupla dos seis campos de inteiros do UUID, que também estão disponíveis como seis atributos individuais e dois atributos derivados:

Campo	Significado
UUID.time_low¶	Os primeiros 32 bits do UUID. Relevante apenas para a versão 1.
UUID.time_mid¶	Os próximos 16 bits do UUID. Relevante apenas para a versão 1.
UUID.time_hi_version¶	Os próximos 16 bits do UUID. Relevante apenas para a versão 1.
UUID.clock_seq_hi_variant¶	Os próximos 8 bits do UUID. Relevante apenas para as versões 1 e 6.
UUID.clock_seq_low¶	Os próximos 8 bits do UUID. Relevante apenas para as versões 1 e 6.
UUID.node¶	Os últimos 48 bits do UUID. Relevante apenas para a versão 1.
UUID.time¶	O registro de data e hora de 60 bits como uma contagem de intervalos de 100 nanossegundos desde a época gregoriana (1582-10-15 00:00:00) para as versões 1 e 6, ou o registro de data e hora de 48 bits em milissegundos desde a época Unix (1970-01-01 00:00:00) para a versão 7.
UUID.clock_seq¶	Número de sequência de 14 bits. Relevante apenas para as versões 1 e 6.

UUID.hex¶: O UUID como uma sequência hexadecimal de 32 caracteres minúsculos.

UUID.int¶: O UUID como um inteiro de 128 bits.

UUID.urn¶: O UUID como um URN conforme especificado no RFC 9562.

UUID.variant¶: A variante UUID, que determina o layout interno do UUID. Esta será uma das constantes RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT ou RESERVED_FUTURE.

UUID.version¶: O número da versão do UUID (1 a 8, significativo somente quando a variante é RFC_4122).

Alterado na versão 3.14: Adicionadas versões 6, 7 e 8 do UUID.

UUID.is_safe¶: Uma enumeração de SafeUUID que indica se a plataforma gerou o UUID de forma segura para multiprocessamento.

Adicionado na versão 3.7.

O módulo uuid define as seguintes funções:

uuid.getnode()¶: Obtém o endereço de hardware como um inteiro positivo de 48 bits. Na primeira vez que isso for executado, ele pode iniciar um programa separado, o que pode ser bem lento. Se todas as tentativas de obter o endereço de hardware falharem, escolhemos um número aleatório de 48 bits com o bit multicast (bit menos significativo do primeiro octeto) definido como 1, conforme recomendado no RFC 4122. “Endereço de hardware” significa o endereço MAC de uma interface de rede. Em uma máquina com várias interfaces de rede, endereços MAC administrados universalmente (ou seja, onde o segundo bit menos significativo do primeiro octeto é não definido) serão preferidos em relação a endereços MAC administrados localmente, mas sem nenhuma outra garantia de ordenação.

Alterado na versão 3.7: Endereços MAC administrados universalmente são preferidos em vez de endereços MAC administrados localmente, pois os primeiros têm garantia de serem globalmente exclusivos, enquanto os últimos não.

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

Gera um UUID a partir de um ID de host, número de sequência e hora atual de acordo com RFC 9562, §5.1.

Quando node não é especificado, getnode() é usado para obter o endereço de hardware como um inteiro positivo de 48 bits. Quando um número de sequência clock_seq não é especificado, um inteiro positivo pseudoaleatório de 14 bits é gerado.

Se node ou clock_seq excederem a contagem de bits esperada, apenas seus bits menos significativos serão mantidos.

uuid.uuid3(namespace, name)¶: Gera um UUID com base no hash MD5 de um identificador de espaço de nomes (que é um UUID) e um nome (que é um objeto bytes ou uma string que será codificada usando UTF-8) de acordo com RFC 9562, §5.3.

uuid.uuid4()¶: Gera um UUID aleatório em um método criptograficamente seguro de acordo com RFC 9562, §5.4.

uuid.uuid5(namespace, name)¶: Gera um UUID com base no hash SHA-1 de um identificador de espaço de nomes (que é um UUID) e um nome (que é um objeto bytes ou uma string que será codificada usando UTF-8) de acordo com RFC 9562, §5.5.

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

Gera um UUID a partir de um número de sequência e hora atual de acordo com RFC 9562, §5.6.

Esta é uma alternativa ao uuid1() para melhorar a localidade do banco de dados.

Quando node não é especificado, getnode() é usado para obter o endereço de hardware como um inteiro positivo de 48 bits. Quando um número de sequência clock_seq não é especificado, um inteiro positivo pseudoaleatório de 14 bits é gerado.

Se node ou clock_seq excederem a contagem de bits esperada, apenas seus bits menos significativos serão mantidos.

Adicionado na versão 3.14.

uuid.uuid7()¶

Gera um UUID baseado em tempo de acordo com RFC 9562, §5.7.

Para portabilidade entre plataformas sem precisão de submilissegundos, os UUIDs produzidos por esta função incorporam um registro de data e hora de 48 bits e usam um contador de 42 bits para garantir a monotonicidade dentro de um milissegundo.

Adicionado na versão 3.14.

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

Gera um UUID pseudoaleatório de acordo com RFC 9562, §5.8.

Quando especificados, espera-se que os parâmetros a, b e c sejam inteiros positivos de 48, 12 e 62 bits, respectivamente. Se excederem a contagem de bits esperada, apenas os bits menos significativos serão mantidos; argumentos não especificados são substituídos por um inteiro pseudoaleatório de tamanho apropriado.

Por padrão, a, b e c não são gerados por um gerador de números pseudoaleatórios criptograficamente seguro (CSPRNG). Use uuid4() quando um UUID precisar ser usado em um contexto de segurança sensível.

Adicionado na versão 3.14.

O módulo uuid define os seguintes identificadores de espaço de nomes para uso com uuid3() ou uuid5().

uuid.NAMESPACE_DNS¶: Quando esse espaço de nomes é especificado, a string name é um nome de domínio totalmente qualificado.

uuid.NAMESPACE_URL¶: Quando esse espaço de nomes é especificado, a string name é uma URL.

uuid.NAMESPACE_OID¶: Quando esse espaço de nomes é especificado, a string name é um OID ISO.

uuid.NAMESPACE_X500¶: Quando esse espaço de nomes é especificado, a string name é um DN X.500 em DER ou um formato de saída de texto.

O módulo uuid define as seguintes constantes para os valores possíveis do atributo variant:

uuid.RESERVED_NCS¶: Reservado para compatibilidade com NCS.

uuid.RFC_4122¶: Especifica o layout do UUID fornecido em RFC 4122. Esta constante é mantida para retrocompatibilidade, mesmo que RFC 4122 tenha sido substituído por RFC 9562.

uuid.RESERVED_MICROSOFT¶: Reservado para compatibilidade com Microsoft.

uuid.RESERVED_FUTURE¶: Reservado para definição futura.

O módulo uuid define os valores especiais de UUID Nil e Max:

uuid.NIL¶: Uma forma especial de UUID que é especificada para ter todos os 128 bits definidos como zero de acordo com RFC 9562, §5.9.

Adicionado na versão 3.14.

uuid.MAX¶: Uma forma especial de UUID que é especificada para ter todos os 128 bits definidos como um, de acordo com RFC 9562, §5.10.

Adicionado na versão 3.14.

Ver também

RFC 9562 - Um espaço de nomes de URN de identificador universalmente exclusivo (UUID): Esta especificação define um espaço de nomes de Uniform Resource Name para UUIDs, o formato interno de UUIDs e métodos de geração de UUIDs.

Uso na linha de comando¶

Adicionado na versão 3.12.

O módulo uuid pode ser invocado como um script na linha de comando:

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n ESPAÇOS-DE-NOME] [-N NOME]

As seguintes opções são aceitas:

-h, --help¶: Mostra a mensagem de ajuda e sai.

-u <uuid>¶
--uuid <uuid>¶: Especifica o nome da função a ser usada para gerar o uuid. Por padrão, uuid4() é usado.

Alterado na versão 3.14: Permite gerar versões 6, 7 e 8 do UUID.

-n <namespace>¶
--namespace <namespace>¶: O espaço de nomes é um UUID, ou @ns onde ns é um UUID predefinido bem conhecido endereçado pelo nome do espaço de nomes. Como @dns, @url, @oid e @x500. Necessário apenas para funções uuid3() / uuid5().

-N <name>¶
--name <name>¶: O nome usado como parte da geração do uuid. Requerido apenas para funções uuid3() / uuid5().

-C <num>¶
--count <num>¶: Gera num novos UUIDs.

Adicionado na versão 3.14.

Exemplo¶

Aqui estão alguns exemplos de uso típico do módulo uuid:

>>> 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')

Exemplo de linha de comando¶

Aqui estão alguns exemplos de uso típico da interface de linha de comando do uuid:

# gera um UUID aleatório - por padrão uuid4() é usado
$ python -m uuid

# gera um UUID usando uuid1()
$ python -m uuid -u uuid1

# gera um UUID usando uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

# gera 42 UUIDs aleatórios
$ python -m uuid -C 42

`uuid` — Objetos UUID conforme RFC 9562¶

Uso na linha de comando¶

Exemplo¶

Exemplo de linha de comando¶

Tabela de Conteúdo

Tópico anterior

Próximo tópico

Esta página

uuid — Objetos UUID conforme RFC 9562¶

Uso na linha de comando¶

Exemplo¶

Exemplo de linha de comando¶

`uuid` — Objetos UUID conforme RFC 9562¶