"uuid" --- UUID objects according to **RFC 9562**
*************************************************

**Code source :** 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.

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)

   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 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. 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 as a count of 100-nanosecond  |
|                                                    | intervals since Gregorian epoch (1582-10-15        |
|                                                    | 00:00:00) for versions 1 and 6, or the 48-bit      |
|                                                    | timestamp in milliseconds since Unix epoch         |
|                                                    | (1970-01-01 00:00:00) for version 7.               |
+----------------------------------------------------+----------------------------------------------------+
| UUID.clock_seq                                     | The 14-bit sequence number. Only relevant to       |
|                                                    | versions 1 and 6.                                  |
+----------------------------------------------------+----------------------------------------------------+

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

   The UUID as a URN as specified in **RFC 9562**.

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

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

   Modifié dans la version 3.14: Added UUID versions 6, 7 and 8.

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)

   Generate a UUID from a host ID, sequence number, and the current
   time according to **RFC 9562, §5.1**.

   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.

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) according to **RFC 9562, §5.3**.

uuid.uuid4()

   Generate a random UUID in a cryptographically-secure method
   according to **RFC 9562, §5.4**.

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) according to **RFC 9562, §5.5**.

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

   Generate a UUID from a sequence number and the current time
   according to **RFC 9562, §5.6**.

   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.

   Ajouté dans la version 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.

   Ajouté dans la version 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.

   By default, *a*, *b* and *c* are not generated by a
   cryptographically secure pseudo-random number generator (CSPRNG).
   Use "uuid4()" when a UUID needs to be used in a security-sensitive
   context.

   Ajouté dans la version 3.14.

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

   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

   Réservé pour la compatibilité Microsoft.

uuid.RESERVED_FUTURE

   Réservé pour un usage futur.

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

   Ajouté dans la version 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**.

   Ajouté dans la version 3.14.

Voir aussi:

  **RFC 9562** - 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,uuid6,uuid7,uuid8}] [-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.

   Modifié dans la version 3.14: Allow generating UUID versions 6, 7
   and 8.

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

-C <num>
--count <num>

   Generate *num* fresh UUIDs.

   Ajouté dans la version 3.14.


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

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


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

   # generate 42 random UUIDs
   $ python -m uuid -C 42
