uuid --- UUID objects according to RFC 4122

Code source : Lib/uuid.py

---

Ce module exporte des objets UUID immuables (de la classe UUID) et les fonctions uuid1(), uuid3(), uuid4(), uuid5() permettant de générer des UUID de version 1, 3, 4 et 5 tels que définis dans la RFC 4122.

Utilisez uuid1() ou uuid4() si votre but est de produire un identifiant unique. Notez que uuid1() peut dévoiler des informations personnelles car l'UUID produit contient l'adresse réseau de l'ordinateur. En revanche, uuid4() génère un UUID aléatoire.

Depending on support from the underlying platform, uuid1() may or may not return a "safe" UUID. A safe UUID is one which is generated using synchronization methods that ensure no two processes can obtain the same UUID. All instances of UUID have an is_safe attribute which relays any information about the UUID's safety, using this enumeration:

class uuid.SafeUUID

Ajouté dans la version 3.7.

safe

L'UUID a été généré par la plateforme en utilisant une méthode sûre dans un contexte de parallélisme par processus.

unsafe

L'UUID n'a pas été généré par une méthode sûre dans un contexte de parallélisme par processus.

unknown

La plateforme ne précise pas si l'UUID a été généré de façon sûre ou non.

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

Produit un UUID à partir soit d'une chaîne de 32 chiffres hexadécimaux, soit une chaîne de 16 octets gros-boutiste (argument bytes), soit une chaîne de 16 octets petit-boutiste (argument bytes_le), soit un sextuplet d'entiers (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) (argument fields), soit un unique entier sur 128 bits (argument int). Lorsque la fonction reçoit une chaîne de chiffres hexadécimaux, les accolades, les tirets et le préfixe URN sont facultatifs. Par exemple, toutes les expressions ci-dessous génèrent le même 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)

Un seul des arguments hex, bytes, bytes_le, fields ou int doit être spécifié. L'argument version est optionnel : s'il est spécifié, l'UUID généré aura pour numéro de version et de variante la valeur indiquée dans la RFC 4122, remplaçant les bits idoines de hex, bytes, bytes_le, fields ou int.

La comparaison de deux objets UUID se fait en comparant leurs attributs UUID.int. La comparaison avec un objet autre qu'un UUID lève une exception TypeError.

str(uuid) renvoie une chaîne de caractères de la forme 12345678-1234-5678-1234-567812345678 représentant l'UUID par une chaîne de 32 chiffres hexadécimaux.

Les instances de UUID possèdent les attributs suivants en lecture seule :

UUID.bytes

L'UUID représenté comme une chaîne de 16 octets (contenant les six champs entiers dans l'ordre gros-boutiste).

UUID.bytes_le

L'UUID représenté comme une chaîne de 16 octets (avec time_low, time_mid et time_hi_version dans l'ordre petit-boutiste).

UUID.fields

Un sextuplet contenant les champs entiers de l'UUID, également accessibles en tant que six attributs individuels et deux attributs dérivés :

Champ	Signification
UUID.time_low	The first 32 bits of the UUID.
UUID.time_mid	The next 16 bits of the UUID.
UUID.time_hi_version	The next 16 bits of the UUID.
UUID.clock_seq_hi_variant	The next 8 bits of the UUID.
UUID.clock_seq_low	The next 8 bits of the UUID.
UUID.node	The last 48 bits of the UUID.
UUID.time	The 60-bit timestamp.
UUID.clock_seq	The 14-bit sequence number.

UUID.hex

The UUID as a 32-character lowercase hexadecimal string.

UUID.int

Représentation de l'UUId sous forme d'un entier de 128 bits.

UUID.urn

Représentation de l'UUID sous forme d'URN tel que spécifié dans la RFC 4122.

UUID.variant

Variante de l'UUID. Celle-ci détermine l'agencement interne de l'UUID. Les valeurs possibles sont les constantes suivantes : RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT ou RESERVED_FUTURE.

UUID.version

Numéro de version de l'UUID (de 1 à 5). Cette valeur n'a de sens que dans le cas de la variante RFC_4122.

UUID.is_safe

Valeur de l'énumération SafeUUID indiquant si la plateforme a généré l'UUID d'une façon sûre dans un contexte de parallélisme par processus.

Ajouté dans la version 3.7.

Le module uu définit les fonctions suivantes :

uuid.getnode()

Renvoie l'adresse réseau matérielle sous forme d'un entier positif sur 48 bits. Cette fonction peut faire appel à un programme externe relativement lent lors de sa première exécution. Si toutes les tentatives d'obtenir l'adresse matérielle échouent, un nombre aléatoire sur 48 bit avec le bit de multicast (bit de poids faible du premier octet) à 1 est généré, comme recommandé par la RFC 4122. Ici, « adresse matérielle » correspond à l'adresse MAC d'une interface réseau. Sur une machine avec plusieurs interfaces réseau, les adresses MAC de type UUA (universally administered address, pour lesquelles le second bit de poids faible est à zéro) sont prioritaires par rapport aux autres adresses MAC. Aucune autre garantie n'est donnée sur l'ordre dans lequel les interfaces sont choisies.

Modifié dans la version 3.7: Les adresses MAC de type UUA sont préférées par rapport aux adresses locales car ces dernières ne sont pas nécessairement uniques.

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

Génère un UUID à partir d'un identifiant hôte, d'un numéro de séquence et de l'heure actuelle. Si node n'est pas spécifié, la fonction getnode() est appelée pour obtenir l'adresse matérielle. clock_seq est utilisé comme numéro de séquence s'il est spécifié, sinon un numéro aléatoire sur 14 bits est utilisé à la place.

uuid.uuid3(namespace, name)

Generate a UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

uuid.uuid4()

Génère un UUID aléatoire.

uuid.uuid5(namespace, name)

Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

Le module uuid définit les identifiants d'espaces de noms suivants (pour uuid3() et uuid5()).

uuid.NAMESPACE_DNS

When this namespace is specified, the name string is a fully qualified domain name.

uuid.NAMESPACE_URL

Lorsque cet espace de nom est spécifié, la chaîne name doit être une URL.

uuid.NAMESPACE_OID

Lorsque cet espace de nom est spécifié, la chaîne name doit être un OID ISO.

uuid.NAMESPACE_X500

Lorsque cet espace de nom est spécifié, la chaîne name doit être un DN X.500 au format texte ou DER.

The uuid module defines the following constants for the possible values of the variant attribute:

uuid.RESERVED_NCS

Réservé pour la compatibilité NCS.

uuid.RFC_4122

Utilise l'agencement des UUID de la RFC 4122.

uuid.RESERVED_MICROSOFT

Réservé pour la compatibilité Microsoft.

uuid.RESERVED_FUTURE

Réservé pour un usage futur.

Voir aussi

RFC 4122 – A Universally Unique IDentifier (UUID) URN Namespace

Cette spécification (en anglais) définit un espace de noms Uniform Resource Name pour les UUID, leur format interne et les méthodes permettant de les générer.

Utilisation en ligne de commande.

Ajouté dans la version 3.12.

The uuid module can be executed as a script from the command line.

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

Les options suivantes sont acceptées :

-h, --help

Affiche un message d'aide et quitte.

-u <uuid>

--uuid <uuid>

Specify the function name to use to generate the uuid. By default uuid4() is used.

-n <namespace>

--namespace <namespace>

The namespace is a UUID, or @ns where ns is a well-known predefined UUID addressed by namespace name. Such as @dns, @url, @oid, and @x500. Only required for uuid3() / uuid5() functions.

-N <name>

--name <name>

The name used as part of generating the uuid. Only required for uuid3() / uuid5() functions.

Exemple

Voici quelques exemples classiques d'utilisation du module 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')

Command-Line Example

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