# `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