`uuid` — UUID objects according to RFC 9562¶

Código-fonte: Lib/uuid.py

This module provides immutable UUID objects (the UUID class) and functions for generating UUIDs corresponding to a specific UUID version as specified in RFC 9562 (which supersedes RFC 4122), for example, uuid1() for UUID version 1, uuid3() for UUID version 3, and so on. Note that UUID version 2 is deliberately omitted as it is outside the scope of the 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)

Exactly one of hex, bytes, bytes_le, fields, or int must be given. The version argument is optional; if given, the resulting UUID will have its variant and version number set according to RFC 9562, overriding bits in the given hex, bytes, bytes_le, fields, or int.

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¶	The first 32 bits of the UUID. Only relevant to version 1.
UUID.time_mid¶	The next 16 bits of the UUID. Only relevant to version 1.
UUID.time_hi_version¶	The next 16 bits of the UUID. Only relevant to version 1.
UUID.clock_seq_hi_variant¶	The next 8 bits of the UUID. Only relevant to versions 1 and 6.
UUID.clock_seq_low¶	The next 8 bits of the UUID. Only relevant to versions 1 and 6.
UUID.node¶	The last 48 bits of the UUID. Only relevant to version 1.
UUID.time¶	The 60-bit timestamp for version 1 and 6, or the 48-bit timestamp for version 7.
UUID.clock_seq¶	The 14-bit sequence number. Only relevant to versions 1 and 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¶: The UUID as a URN as specified in 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¶: The UUID version number (1 through 8, meaningful only when the variant is RFC_4122).

Alterado na versão 3.14: Added UUID versions 6, 7 and 8.

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. Se node não for fornecido, getnode() é usado para obter o endereço de hardware. Se clock_seq for fornecido, ele é usado como o número de sequência; caso contrário, um número de sequência aleatório de 14 bits é escolhido.

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

uuid.uuid4()¶: Gera um UUID aleatório.

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

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

Generate a UUID from a sequence number and the current time according to RFC 9562. This is an alternative to uuid1() to improve database locality.

When node is not specified, getnode() is used to obtain the hardware address as a 48-bit positive integer. When a sequence number clock_seq is not specified, a pseudo-random 14-bit positive integer is generated.

If node or clock_seq exceed their expected bit count, only their least significant bits are kept.

Adicionado na versão 3.14.

uuid.uuid7()¶

Generate a time-based UUID according to RFC 9562, §5.7.

For portability across platforms lacking sub-millisecond precision, UUIDs produced by this function embed a 48-bit timestamp and use a 42-bit counter to guarantee monotonicity within a millisecond.

Adicionado na versão 3.14.

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

Generate a pseudo-random UUID according to RFC 9562, §5.8.

When specified, the parameters a, b and c are expected to be positive integers of 48, 12 and 62 bits respectively. If they exceed their expected bit count, only their least significant bits are kept; non-specified arguments are substituted for a pseudo-random integer of appropriate size.

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¶: Specifies the UUID layout given in RFC 4122. This constant is kept for backward compatibility even though RFC 4122 has been superseded by RFC 9562.

uuid.RESERVED_MICROSOFT¶: Reservado para compatibilidade com Microsoft.

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

The uuid module defines the special Nil and Max UUID values:

uuid.NIL¶: A special form of UUID that is specified to have all 128 bits set to zero according to RFC 9562, §5.9.

Adicionado na versão 3.14.

uuid.MAX¶: A special form of UUID that is specified to have all 128 bits set to one according to RFC 9562, §5.10.

Adicionado na versão 3.14.

Ver também

RFC 9562 - A Universally Unique IDentifier (UUID) URN Namespace: 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 NAMESPACE] [-N NAME]

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: Allow generating UUID versions 6, 7 and 8.

-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>¶: Generate num fresh UUIDs.

Adicionado na versão 3.14.0a6 (unreleased).

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

Exemplo de linha de comando¶

Here are some examples of typical usage of the uuid command-line interface:

# 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

`uuid` — UUID objects according to 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 — UUID objects according to RFC 9562¶

Uso na linha de comando¶

Exemplo¶

Exemplo de linha de comando¶

`uuid` — UUID objects according to RFC 9562¶