"uuid" — Objets UUID d'après la **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.

En fonction du système d'exploitation, les UUID "uuid1()" peuvent ne
pas être « sûrs ». Un UUID est considéré sûr s'il est généré avec des
techniques de synchronisation qui garantissent que deux processus ne
peuvent obtenir le même UUID. Toutes les instances de "UUID" possèdent
un attribut "is_safe" qui indique le niveau de sûreté de l'UUID selon
l'énumération suivante :

class uuid.SafeUUID

   Nouveau 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                   |
   |================================|=================================|
   | "time_low"                     | les 32 premiers bits de l'UUID  |
   +--------------------------------+---------------------------------+
   | "time_mid"                     | les 16 bits suivants de l'UUID  |
   +--------------------------------+---------------------------------+
   | "time_hi_version"              | les 16 bits suivants de l'UUID  |
   +--------------------------------+---------------------------------+
   | "clock_seq_hi_variant"         | les 8 bits suivants de l'UUID   |
   +--------------------------------+---------------------------------+
   | "clock_seq_low"                | les 8 bits suivants de l'UUID   |
   +--------------------------------+---------------------------------+
   | "node"                         | les derniers 48 bits de l'UUID  |
   +--------------------------------+---------------------------------+
   | "time"                         | l'horodatage sur 60 bits        |
   +--------------------------------+---------------------------------+
   | "clock_seq"                    | le numéro de séquence sur 14    |
   |                                | bits                            |
   +--------------------------------+---------------------------------+

UUID.hex

   Représentation de l'UUID sous forme d'une chaîne de 32 chiffres
   hexadécimaux.

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.

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

   Génère un UUID à partir de l'empreinte MD5 de l'identifiant d'un
   espace de nom (un UUID) et d'un nom (une chaîne de caractères).

uuid.uuid4()

   Génère un UUID aléatoire.

uuid.uuid5(namespace, name)

   Génère un UUID à partir de l'empreinte SHA-1 de l'identifiant d'un
   espace de nom (un UUID) et d'un nom (une chaîne de caractères).

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

uuid.NAMESPACE_DNS

   Lorsque cet espace de nom est spécifié, la chaîne *name* doit être
   un nom de domaine pleinement qualifié (souvent indiqué en anglais
   par *FQDN*).

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.

Le module "uuid" définit les constantes suivantes correspondant aux
valeurs autorisées pour l'attribut "variant" :

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.


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