1:mod:`!uuid` --- UUID objects according to :rfc:`4122` 2====================================================== 3 4.. module:: uuid 5 :synopsis: UUID objects (universally unique identifiers) according to RFC 4122 6.. moduleauthor:: Ka-Ping Yee <ping@zesty.ca> 7.. sectionauthor:: George Yoshida <quiver@users.sourceforge.net> 8 9**Source code:** :source:`Lib/uuid.py` 10 11-------------- 12 13This module provides immutable :class:`UUID` objects (the :class:`UUID` class) 14and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for 15generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`. 16 17If all you want is a unique ID, you should probably call :func:`uuid1` or 18:func:`uuid4`. Note that :func:`uuid1` may compromise privacy since it creates 19a UUID containing the computer's network address. :func:`uuid4` creates a 20random UUID. 21 22Depending on support from the underlying platform, :func:`uuid1` may or may 23not return a "safe" UUID. A safe UUID is one which is generated using 24synchronization methods that ensure no two processes can obtain the same 25UUID. All instances of :class:`UUID` have an :attr:`~UUID.is_safe` attribute 26which relays any information about the UUID's safety, using this enumeration: 27 28.. class:: SafeUUID 29 30 .. versionadded:: 3.7 31 32 .. attribute:: SafeUUID.safe 33 34 The UUID was generated by the platform in a multiprocessing-safe way. 35 36 .. attribute:: SafeUUID.unsafe 37 38 The UUID was not generated in a multiprocessing-safe way. 39 40 .. attribute:: SafeUUID.unknown 41 42 The platform does not provide information on whether the UUID was 43 generated safely or not. 44 45.. class:: UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown) 46 47 Create a UUID from either a string of 32 hexadecimal digits, a string of 16 48 bytes in big-endian order as the *bytes* argument, a string of 16 bytes in 49 little-endian order as the *bytes_le* argument, a tuple of six integers 50 (32-bit *time_low*, 16-bit *time_mid*, 16-bit *time_hi_version*, 51 8-bit *clock_seq_hi_variant*, 8-bit *clock_seq_low*, 48-bit *node*) as the 52 *fields* argument, or a single 128-bit integer as the *int* argument. 53 When a string of hex digits is given, curly braces, hyphens, 54 and a URN prefix are all optional. For example, these 55 expressions all yield the same UUID:: 56 57 UUID('{12345678-1234-5678-1234-567812345678}') 58 UUID('12345678123456781234567812345678') 59 UUID('urn:uuid:12345678-1234-5678-1234-567812345678') 60 UUID(bytes=b'\x12\x34\x56\x78'*4) 61 UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' + 62 b'\x12\x34\x56\x78\x12\x34\x56\x78') 63 UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) 64 UUID(int=0x12345678123456781234567812345678) 65 66 Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must be given. 67 The *version* argument is optional; if given, the resulting UUID will have its 68 variant and version number set according to :rfc:`4122`, overriding bits in the 69 given *hex*, *bytes*, *bytes_le*, *fields*, or *int*. 70 71 Comparison of UUID objects are made by way of comparing their 72 :attr:`UUID.int` attributes. Comparison with a non-UUID object 73 raises a :exc:`TypeError`. 74 75 ``str(uuid)`` returns a string in the form 76 ``12345678-1234-5678-1234-567812345678`` where the 32 hexadecimal digits 77 represent the UUID. 78 79:class:`UUID` instances have these read-only attributes: 80 81.. attribute:: UUID.bytes 82 83 The UUID as a 16-byte string (containing the six integer fields in big-endian 84 byte order). 85 86 87.. attribute:: UUID.bytes_le 88 89 The UUID as a 16-byte string (with *time_low*, *time_mid*, and *time_hi_version* 90 in little-endian byte order). 91 92 93.. attribute:: UUID.fields 94 95 A tuple of the six integer fields of the UUID, which are also available as six 96 individual attributes and two derived attributes: 97 98.. list-table:: 99 100 * - Field 101 - Meaning 102 103 * - .. attribute:: UUID.time_low 104 - The first 32 bits of the UUID. 105 106 * - .. attribute:: UUID.time_mid 107 - The next 16 bits of the UUID. 108 109 * - .. attribute:: UUID.time_hi_version 110 - The next 16 bits of the UUID. 111 112 * - .. attribute:: UUID.clock_seq_hi_variant 113 - The next 8 bits of the UUID. 114 115 * - .. attribute:: UUID.clock_seq_low 116 - The next 8 bits of the UUID. 117 118 * - .. attribute:: UUID.node 119 - The last 48 bits of the UUID. 120 121 * - .. attribute:: UUID.time 122 - The 60-bit timestamp. 123 124 * - .. attribute:: UUID.clock_seq 125 - The 14-bit sequence number. 126 127 128.. attribute:: UUID.hex 129 130 The UUID as a 32-character lowercase hexadecimal string. 131 132 133.. attribute:: UUID.int 134 135 The UUID as a 128-bit integer. 136 137 138.. attribute:: UUID.urn 139 140 The UUID as a URN as specified in :rfc:`4122`. 141 142 143.. attribute:: UUID.variant 144 145 The UUID variant, which determines the internal layout of the UUID. This will be 146 one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`, 147 :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`. 148 149 150.. attribute:: UUID.version 151 152 The UUID version number (1 through 5, meaningful only when the variant is 153 :const:`RFC_4122`). 154 155.. attribute:: UUID.is_safe 156 157 An enumeration of :class:`SafeUUID` which indicates whether the platform 158 generated the UUID in a multiprocessing-safe way. 159 160 .. versionadded:: 3.7 161 162The :mod:`uuid` module defines the following functions: 163 164 165.. function:: getnode() 166 167 Get the hardware address as a 48-bit positive integer. The first time this 168 runs, it may launch a separate program, which could be quite slow. If all 169 attempts to obtain the hardware address fail, we choose a random 48-bit 170 number with the multicast bit (least significant bit of the first octet) 171 set to 1 as recommended in :rfc:`4122`. "Hardware address" means the MAC 172 address of a network interface. On a machine with multiple network 173 interfaces, universally administered MAC addresses (i.e. where the second 174 least significant bit of the first octet is *unset*) will be preferred over 175 locally administered MAC addresses, but with no other ordering guarantees. 176 177 .. versionchanged:: 3.7 178 Universally administered MAC addresses are preferred over locally 179 administered MAC addresses, since the former are guaranteed to be 180 globally unique, while the latter are not. 181 182.. index:: single: getnode 183 184 185.. function:: uuid1(node=None, clock_seq=None) 186 187 Generate a UUID from a host ID, sequence number, and the current time. If *node* 188 is not given, :func:`getnode` is used to obtain the hardware address. If 189 *clock_seq* is given, it is used as the sequence number; otherwise a random 190 14-bit sequence number is chosen. 191 192.. index:: single: uuid1 193 194 195.. function:: uuid3(namespace, name) 196 197 Generate a UUID based on the MD5 hash of a namespace identifier (which is a 198 UUID) and a name (which is a :class:`bytes` object or a string 199 that will be encoded using UTF-8). 200 201.. index:: single: uuid3 202 203 204.. function:: uuid4() 205 206 Generate a random UUID. 207 208.. index:: single: uuid4 209 210 211.. function:: uuid5(namespace, name) 212 213 Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a 214 UUID) and a name (which is a :class:`bytes` object or a string 215 that will be encoded using UTF-8). 216 217.. index:: single: uuid5 218 219The :mod:`uuid` module defines the following namespace identifiers for use with 220:func:`uuid3` or :func:`uuid5`. 221 222 223.. data:: NAMESPACE_DNS 224 225 When this namespace is specified, the *name* string is a fully qualified domain 226 name. 227 228 229.. data:: NAMESPACE_URL 230 231 When this namespace is specified, the *name* string is a URL. 232 233 234.. data:: NAMESPACE_OID 235 236 When this namespace is specified, the *name* string is an ISO OID. 237 238 239.. data:: NAMESPACE_X500 240 241 When this namespace is specified, the *name* string is an X.500 DN in DER or a 242 text output format. 243 244The :mod:`uuid` module defines the following constants for the possible values 245of the :attr:`~UUID.variant` attribute: 246 247 248.. data:: RESERVED_NCS 249 250 Reserved for NCS compatibility. 251 252 253.. data:: RFC_4122 254 255 Specifies the UUID layout given in :rfc:`4122`. 256 257 258.. data:: RESERVED_MICROSOFT 259 260 Reserved for Microsoft compatibility. 261 262 263.. data:: RESERVED_FUTURE 264 265 Reserved for future definition. 266 267 268.. seealso:: 269 270 :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace 271 This specification defines a Uniform Resource Name namespace for UUIDs, the 272 internal format of UUIDs, and methods of generating UUIDs. 273 274 275.. _uuid-cli: 276 277Command-Line Usage 278------------------ 279 280.. versionadded:: 3.12 281 282The :mod:`uuid` module can be executed as a script from the command line. 283 284.. code-block:: sh 285 286 python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME] 287 288The following options are accepted: 289 290.. program:: uuid 291 292.. option:: -h, --help 293 294 Show the help message and exit. 295 296.. option:: -u <uuid> 297 --uuid <uuid> 298 299 Specify the function name to use to generate the uuid. By default :func:`uuid4` 300 is used. 301 302.. option:: -n <namespace> 303 --namespace <namespace> 304 305 The namespace is a ``UUID``, or ``@ns`` where ``ns`` is a well-known predefined UUID 306 addressed by namespace name. Such as ``@dns``, ``@url``, ``@oid``, and ``@x500``. 307 Only required for :func:`uuid3` / :func:`uuid5` functions. 308 309.. option:: -N <name> 310 --name <name> 311 312 The name used as part of generating the uuid. Only required for 313 :func:`uuid3` / :func:`uuid5` functions. 314 315 316.. _uuid-example: 317 318Example 319------- 320 321Here are some examples of typical usage of the :mod:`uuid` module:: 322 323 >>> import uuid 324 325 >>> # make a UUID based on the host ID and current time 326 >>> uuid.uuid1() 327 UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') 328 329 >>> # make a UUID using an MD5 hash of a namespace UUID and a name 330 >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') 331 UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') 332 333 >>> # make a random UUID 334 >>> uuid.uuid4() 335 UUID('16fd2706-8baf-433b-82eb-8c7fada847da') 336 337 >>> # make a UUID using a SHA-1 hash of a namespace UUID and a name 338 >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') 339 UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') 340 341 >>> # make a UUID from a string of hex digits (braces and hyphens ignored) 342 >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') 343 344 >>> # convert a UUID to a string of hex digits in standard form 345 >>> str(x) 346 '00010203-0405-0607-0809-0a0b0c0d0e0f' 347 348 >>> # get the raw 16 bytes of the UUID 349 >>> x.bytes 350 b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' 351 352 >>> # make a UUID from a 16-byte string 353 >>> uuid.UUID(bytes=x.bytes) 354 UUID('00010203-0405-0607-0809-0a0b0c0d0e0f') 355 356 357.. _uuid-cli-example: 358 359Command-Line Example 360-------------------- 361 362Here are some examples of typical usage of the :mod:`uuid` command line interface: 363 364.. code-block:: shell 365 366 # generate a random uuid - by default uuid4() is used 367 $ python -m uuid 368 369 # generate a uuid using uuid1() 370 $ python -m uuid -u uuid1 371 372 # generate a uuid using uuid5 373 $ python -m uuid -u uuid5 -n @url -N example.com 374 375