uuid — UUID objects according to RFC 9562

Código fuente: Lib/uuid.py

---

This module provides immutable UUID objects (the UUID class) and the functions uuid1(), uuid3(), uuid4(), uuid5(), and uuid.uuid8() for generating version 1, 3, 4, 5, and 8 UUIDs as specified in RFC 9562 (which supersedes RFC 4122).

Si todo lo que quieres es una identificación única, probablemente deberías llamar a uuuid1() o uuid4(). Ten en cuenta que uuid1() puede comprometer la privacidad ya que crea un UUID que contiene la dirección de red del ordenador. uuid4() crea un UUID aleatorio.

Dependiendo del soporte de la plataforma subyacente, uuid1() puede o no retornar un UUID «seguro». Un UUID seguro es aquel que se genera mediante métodos de sincronización que aseguran que ningún proceso pueda obtener el mismo UUID. Todas las instancias de UUID tienen un atributo is_safe que transmite cualquier información sobre la seguridad del UUID, usando esta enumeración:

class uuid.SafeUUID

Added in version 3.7.

safe

El UUID fue generado por la plataforma de una manera segura para multiprocesamiento.

unsafe

El UUID no fue generado por la plataforma de una manera segura de multiprocesamiento.

unknown

La plataforma no proporciona información sobre si el UUID se generó de forma segura o no.

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

Crea un UUID a partir de una cadena de 32 dígitos hexadecimales, una cadena de 16 bytes en orden big-endian como el argumento bytes, una cadena de 16 bytes en orden little-endian como el argumento bytes_le, una tupla de seis enteros (32-bit time_low, 16-bit time_mid, 16-bit time_hi_version, 8-bit clock_seq_hi_variant, 8-bit clock_seq_low, 48-bit node) como el argumento fields, o un solo entero de 128-bit como el argumento int. Cuando se da una cadena de dígitos hexadecimales, los corchetes, los guiones y el prefijo URN son todos opcionales. Por ejemplo, todas estas expresiones producen el mismo 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.

La comparación de los objetos UUID se hace mediante la comparación de sus atributos UID.int. La comparación con un objeto no UUID produce un TypeError.

str(uuid) retorna una cadena en la forma 12345678-1234-5678-1234-567812345678 donde los 32 dígitos hexadecimales representan el UUID.

Las instancias de UUID tienen estos atributos de sólo lectura:

UUID.bytes

El UUID como una cadena de 16 bytes (que contiene los seis campos enteros en orden de bytes big-endian).

UUID.bytes_le

El UUID como una cadena de 16 bytes (con time_low, time_mid, y time_hi_version en el orden de bytes little-endian).

UUID.fields

Una tupla de los seis campos enteros de la UUID, que también están disponibles como seis atributos individuales y dos atributos derivados:

Campo	Significado
UUID.time_low	los primeros 32 bits del UUID.
UUID.time_mid	los siguientes 16 bits del UUID.
UUID.time_hi_version	los siguientes 16 bits del UUID.
UUID.clock_seq_hi_variant	los siguientes 8 bits del UUID.
UUID.clock_seq_low	los siguientes 8 bits del UUID.
UUID.node	los últimos 48 bits del UUID.
UUID.time	el timestamp de 60-bit.
UUID.clock_seq	el número de secuencia de 14-bit.

UUID.hex

El UUID como una cadena hexadecimal en minúsculas de 32 caracteres.

UUID.int

El UUID como un entero de 128 bits.

UUID.urn

The UUID as a URN as specified in RFC 9562.

UUID.variant

La variante UUID, que determina la disposición interna del UUID. Esta será una de las constantes RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, o RESERVED_FUTURE.

UUID.version

The UUID version number (1 through 8, meaningful only when the variant is RFC_4122).

Distinto en la versión 3.14.0a1 (unreleased): Added UUID version 8.

UUID.is_safe

Una enumeración de SafeUUID que indica si la plataforma generó el UUID de forma segura para el multiprocesamiento.

Added in version 3.7.

El módulo uuid define las siguientes funciones:

uuid.getnode()

Obtiene la dirección del hardware como un entero positivo de 48 bits. La primera vez que esto se ejecute, puede lanzar un programa separado, que podría ser bastante lento. Si todos los intentos de obtener la dirección de hardware fallan, elegimos un número aleatorio de 48 bits con el bit multicast (el bit menos significativo del primer octeto) puesto a 1 como se recomienda en RFC 4122. «Dirección de hardware» significa la dirección MAC de una interfaz de red. En una máquina con múltiples interfaces de red, las direcciones MAC administradas universalmente (es decir, donde el segundo bit menos significativo del primer octeto es unset) se preferirán a las direcciones MAC administradas localmente, pero sin otras garantías de orden.

Distinto en la versión 3.7: Se prefieren las direcciones MAC administradas universalmente a las administradas localmente, ya que se garantiza que las primeras son únicas a nivel mundial, mientras que las segundas no lo son.

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

Genera un UUID a partir de un ID de host, número de secuencia y la hora actual. Si no se da node, se usa getnode() para obtener la dirección del hardware. Si se da clock_seq, se utiliza como número de secuencia; de lo contrario se elige un número de secuencia aleatorio de 14 bits.

uuid.uuid3(namespace, name)

Genera un UUID basado en el hash MD5 de un identificador de espacio de nombres (que es un UUID) y un nombre (que es un objeto bytes o una cadena de caracteres que se codificará usando UTF-8).

uuid.uuid4()

Genera un UUID aleatorio.

uuid.uuid5(namespace, name)

Genera un UUID basado en el hash SHA-1 de un identificador de espacio de nombres (que es un UUID) y un nombre (que es un objeto bytes o una cadena de caracteres que se codificará usando UTF-8).

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.

Added in version 3.14.0a1 (unreleased).

El módulo uuuid define los siguientes identificadores de espacios de nombres para su uso con uuid3() o uuuid5().

uuid.NAMESPACE_DNS

Cuando se especifica este espacio de nombres, la cadena name es un nombre de dominio completamente calificado.

uuid.NAMESPACE_URL

Cuando se especifica este espacio de nombres, la cadena name es una URL.

uuid.NAMESPACE_OID

Cuando se especifica este espacio de nombres, la cadena name es un OID ISO.

uuid.NAMESPACE_X500

Cuando se especifica este espacio de nombres, la cadena name es un X.500 DN en DER o un formato de salida de texto.

El módulo uuid define las siguientes constantes para los posibles valores del atributo variant:

uuid.RESERVED_NCS

Reservado para la compatibilidad con 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 la compatibilidad con Microsoft.

uuid.RESERVED_FUTURE

Reservado para una futura definición.

Ver también

RFC 9562 - A Universally Unique IDentifier (UUID) URN Namespace

Esta especificación define un espacio de nombres de recursos uniforme para los UUID, el formato interno de los UUID y los métodos de generación de los UUID.

Uso de la línea de comandos

Added in version 3.12.

El módulo uuid se puede ejecutar como un script desde la línea de comando.

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid8}] [-n NAMESPACE] [-N NAME]

Se aceptan las siguientes opciones:

-h, --help

Muestra el mensaje de ayuda y libera la linea de comando.

-u <uuid>

--uuid <uuid>

Especifica el nombre de la función que se utilizará para generar el uuid. Por defecto se utiliza uuid4().

Added in version 3.14.0a1 (unreleased): Allow generating UUID version 8.

-n <namespace>

--namespace <namespace>

El espacio de nombres es un UUID o @ns donde ns es un UUID predefinido conocido dirigido por el nombre del espacio de nombres. Como @dns, @url, @oid y @x500. Solo se requiere para las funciones uuid3() / uuid5().

-N <name>

--name <name>

El nombre utilizado como parte de la generación del uuid. Solo se requiere para las funciones uuid3() / uuid5().

Ejemplo

Aquí hay algunos ejemplos del uso típico del modulo 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')

Ejemplo de línea de comandos

Aquí hay algunos ejemplos del uso típico del modulo uuid:

# 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