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 22 23.. class:: UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None) 24 25 Create a UUID from either a string of 32 hexadecimal digits, a string of 16 26 bytes as the *bytes* argument, a string of 16 bytes in little-endian order as 27 the *bytes_le* argument, a tuple of six integers (32-bit *time_low*, 16-bit 28 *time_mid*, 16-bit *time_hi_version*, 8-bit *clock_seq_hi_variant*, 8-bit 29 *clock_seq_low*, 48-bit *node*) as the *fields* argument, or a single 128-bit 30 integer as the *int* argument. When a string of hex digits is given, curly 31 braces, hyphens, and a URN prefix are all optional. For example, these 32 expressions all yield the same UUID:: 33 34 UUID('{12345678-1234-5678-1234-567812345678}') 35 UUID('12345678123456781234567812345678') 36 UUID('urn:uuid:12345678-1234-5678-1234-567812345678') 37 UUID(bytes=b'\x12\x34\x56\x78'*4) 38 UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' + 39 b'\x12\x34\x56\x78\x12\x34\x56\x78') 40 UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) 41 UUID(int=0x12345678123456781234567812345678) 42 43 Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must be given. 44 The *version* argument is optional; if given, the resulting UUID will have its 45 variant and version number set according to RFC 4122, overriding bits in the 46 given *hex*, *bytes*, *bytes_le*, *fields*, or *int*. 47 48 Comparison of UUID objects are made by way of comparing their 49 :attr:`UUID.int` attributes. Comparison with a non-UUID object 50 raises a :exc:`TypeError`. 51 52 ``str(uuid)`` returns a string in the form 53 ``12345678-1234-5678-1234-567812345678`` where the 32 hexadecimal digits 54 represent the UUID. 55 56:class:`UUID` instances have these read-only attributes: 57 58.. attribute:: UUID.bytes 59 60 The UUID as a 16-byte string (containing the six integer fields in big-endian 61 byte order). 62 63 64.. attribute:: UUID.bytes_le 65 66 The UUID as a 16-byte string (with *time_low*, *time_mid*, and *time_hi_version* 67 in little-endian byte order). 68 69 70.. attribute:: UUID.fields 71 72 A tuple of the six integer fields of the UUID, which are also available as six 73 individual attributes and two derived attributes: 74 75 +------------------------------+-------------------------------+ 76 | Field | Meaning | 77 +==============================+===============================+ 78 | :attr:`time_low` | the first 32 bits of the UUID | 79 +------------------------------+-------------------------------+ 80 | :attr:`time_mid` | the next 16 bits of the UUID | 81 +------------------------------+-------------------------------+ 82 | :attr:`time_hi_version` | the next 16 bits of the UUID | 83 +------------------------------+-------------------------------+ 84 | :attr:`clock_seq_hi_variant` | the next 8 bits of the UUID | 85 +------------------------------+-------------------------------+ 86 | :attr:`clock_seq_low` | the next 8 bits of the UUID | 87 +------------------------------+-------------------------------+ 88 | :attr:`node` | the last 48 bits of the UUID | 89 +------------------------------+-------------------------------+ 90 | :attr:`time` | the 60-bit timestamp | 91 +------------------------------+-------------------------------+ 92 | :attr:`clock_seq` | the 14-bit sequence number | 93 +------------------------------+-------------------------------+ 94 95 96.. attribute:: UUID.hex 97 98 The UUID as a 32-character hexadecimal string. 99 100 101.. attribute:: UUID.int 102 103 The UUID as a 128-bit integer. 104 105 106.. attribute:: UUID.urn 107 108 The UUID as a URN as specified in RFC 4122. 109 110 111.. attribute:: UUID.variant 112 113 The UUID variant, which determines the internal layout of the UUID. This will be 114 one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`, 115 :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`. 116 117 118.. attribute:: UUID.version 119 120 The UUID version number (1 through 5, meaningful only when the variant is 121 :const:`RFC_4122`). 122 123The :mod:`uuid` module defines the following functions: 124 125 126.. function:: getnode() 127 128 Get the hardware address as a 48-bit positive integer. The first time this 129 runs, it may launch a separate program, which could be quite slow. If all 130 attempts to obtain the hardware address fail, we choose a random 48-bit number 131 with its eighth bit set to 1 as recommended in RFC 4122. "Hardware address" 132 means the MAC address of a network interface, and on a machine with multiple 133 network interfaces the MAC address of any one of them may be returned. 134 135.. index:: single: getnode 136 137 138.. function:: uuid1(node=None, clock_seq=None) 139 140 Generate a UUID from a host ID, sequence number, and the current time. If *node* 141 is not given, :func:`getnode` is used to obtain the hardware address. If 142 *clock_seq* is given, it is used as the sequence number; otherwise a random 143 14-bit sequence number is chosen. 144 145.. index:: single: uuid1 146 147 148.. function:: uuid3(namespace, name) 149 150 Generate a UUID based on the MD5 hash of a namespace identifier (which is a 151 UUID) and a name (which is a string). 152 153.. index:: single: uuid3 154 155 156.. function:: uuid4() 157 158 Generate a random UUID. 159 160.. index:: single: uuid4 161 162 163.. function:: uuid5(namespace, name) 164 165 Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a 166 UUID) and a name (which is a string). 167 168.. index:: single: uuid5 169 170The :mod:`uuid` module defines the following namespace identifiers for use with 171:func:`uuid3` or :func:`uuid5`. 172 173 174.. data:: NAMESPACE_DNS 175 176 When this namespace is specified, the *name* string is a fully-qualified domain 177 name. 178 179 180.. data:: NAMESPACE_URL 181 182 When this namespace is specified, the *name* string is a URL. 183 184 185.. data:: NAMESPACE_OID 186 187 When this namespace is specified, the *name* string is an ISO OID. 188 189 190.. data:: NAMESPACE_X500 191 192 When this namespace is specified, the *name* string is an X.500 DN in DER or a 193 text output format. 194 195The :mod:`uuid` module defines the following constants for the possible values 196of the :attr:`variant` attribute: 197 198 199.. data:: RESERVED_NCS 200 201 Reserved for NCS compatibility. 202 203 204.. data:: RFC_4122 205 206 Specifies the UUID layout given in :rfc:`4122`. 207 208 209.. data:: RESERVED_MICROSOFT 210 211 Reserved for Microsoft compatibility. 212 213 214.. data:: RESERVED_FUTURE 215 216 Reserved for future definition. 217 218 219.. seealso:: 220 221 :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace 222 This specification defines a Uniform Resource Name namespace for UUIDs, the 223 internal format of UUIDs, and methods of generating UUIDs. 224 225 226.. _uuid-example: 227 228Example 229------- 230 231Here are some examples of typical usage of the :mod:`uuid` module:: 232 233 >>> import uuid 234 235 >>> # make a UUID based on the host ID and current time 236 >>> uuid.uuid1() 237 UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') 238 239 >>> # make a UUID using an MD5 hash of a namespace UUID and a name 240 >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') 241 UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') 242 243 >>> # make a random UUID 244 >>> uuid.uuid4() 245 UUID('16fd2706-8baf-433b-82eb-8c7fada847da') 246 247 >>> # make a UUID using a SHA-1 hash of a namespace UUID and a name 248 >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') 249 UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') 250 251 >>> # make a UUID from a string of hex digits (braces and hyphens ignored) 252 >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') 253 254 >>> # convert a UUID to a string of hex digits in standard form 255 >>> str(x) 256 '00010203-0405-0607-0809-0a0b0c0d0e0f' 257 258 >>> # get the raw 16 bytes of the UUID 259 >>> x.bytes 260 b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' 261 262 >>> # make a UUID from a 16-byte string 263 >>> uuid.UUID(bytes=x.bytes) 264 UUID('00010203-0405-0607-0809-0a0b0c0d0e0f') 265 266