Debian Codegraph @

Doc/library/uuid.rst

raw
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 <[email protected]>
7 .. sectionauthor:: George Yoshida <[email protected]>
8
9 **Source code:** :source:`Lib/uuid.py`
10
11 --------------
12
13 This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
14 and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for
15 generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`.
16
17 If 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
19 a UUID containing the computer's network address. :func:`uuid4` creates a
20 random UUID.
21
22 Depending on support from the underlying platform, :func:`uuid1` may or may
23 not return a "safe" UUID. A safe UUID is one which is generated using
24 synchronization methods that ensure no two processes can obtain the same
25 UUID. All instances of :class:`UUID` have an :attr:`~UUID.is_safe` attribute
26 which 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
162 The :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
183 .. function:: uuid1(node=None, clock_seq=None)
184
185 Generate a UUID from a host ID, sequence number, and the current time. If *node*
186 is not given, :func:`getnode` is used to obtain the hardware address. If
187 *clock_seq* is given, it is used as the sequence number; otherwise a random
188 14-bit sequence number is chosen.
189
190
191 .. function:: uuid3(namespace, name)
192
193 Generate a UUID based on the MD5 hash of a namespace identifier (which is a
194 UUID) and a name (which is a :class:`bytes` object or a string
195 that will be encoded using UTF-8).
196
197
198 .. function:: uuid4()
199
200 Generate a random UUID.
201
202
203 .. function:: uuid5(namespace, name)
204
205 Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
206 UUID) and a name (which is a :class:`bytes` object or a string
207 that will be encoded using UTF-8).
208
209
210 The :mod:`uuid` module defines the following namespace identifiers for use with
211 :func:`uuid3` or :func:`uuid5`.
212
213
214 .. data:: NAMESPACE_DNS
215
216 When this namespace is specified, the *name* string is a fully qualified domain
217 name.
218
219
220 .. data:: NAMESPACE_URL
221
222 When this namespace is specified, the *name* string is a URL.
223
224
225 .. data:: NAMESPACE_OID
226
227 When this namespace is specified, the *name* string is an ISO OID.
228
229
230 .. data:: NAMESPACE_X500
231
232 When this namespace is specified, the *name* string is an X.500 DN in DER or a
233 text output format.
234
235 The :mod:`uuid` module defines the following constants for the possible values
236 of the :attr:`~UUID.variant` attribute:
237
238
239 .. data:: RESERVED_NCS
240
241 Reserved for NCS compatibility.
242
243
244 .. data:: RFC_4122
245
246 Specifies the UUID layout given in :rfc:`4122`.
247
248
249 .. data:: RESERVED_MICROSOFT
250
251 Reserved for Microsoft compatibility.
252
253
254 .. data:: RESERVED_FUTURE
255
256 Reserved for future definition.
257
258
259 .. seealso::
260
261 :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace
262 This specification defines a Uniform Resource Name namespace for UUIDs, the
263 internal format of UUIDs, and methods of generating UUIDs.
264
265
266 .. _uuid-cli:
267
268 Command-Line Usage
269 ------------------
270
271 .. versionadded:: 3.12
272
273 The :mod:`uuid` module can be executed as a script from the command line.
274
275 .. code-block:: sh
276
277 python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME]
278
279 The following options are accepted:
280
281 .. program:: uuid
282
283 .. option:: -h, --help
284
285 Show the help message and exit.
286
287 .. option:: -u <uuid>
288 --uuid <uuid>
289
290 Specify the function name to use to generate the uuid. By default :func:`uuid4`
291 is used.
292
293 .. option:: -n <namespace>
294 --namespace <namespace>
295
296 The namespace is a ``UUID``, or ``@ns`` where ``ns`` is a well-known predefined UUID
297 addressed by namespace name. Such as ``@dns``, ``@url``, ``@oid``, and ``@x500``.
298 Only required for :func:`uuid3` / :func:`uuid5` functions.
299
300 .. option:: -N <name>
301 --name <name>
302
303 The name used as part of generating the uuid. Only required for
304 :func:`uuid3` / :func:`uuid5` functions.
305
306
307 .. _uuid-example:
308
309 Example
310 -------
311
312 Here are some examples of typical usage of the :mod:`uuid` module::
313
314 >>> import uuid
315
316 >>> # make a UUID based on the host ID and current time
317 >>> uuid.uuid1()
318 UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
319
320 >>> # make a UUID using an MD5 hash of a namespace UUID and a name
321 >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
322 UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
323
324 >>> # make a random UUID
325 >>> uuid.uuid4()
326 UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
327
328 >>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
329 >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
330 UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
331
332 >>> # make a UUID from a string of hex digits (braces and hyphens ignored)
333 >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
334
335 >>> # convert a UUID to a string of hex digits in standard form
336 >>> str(x)
337 '00010203-0405-0607-0809-0a0b0c0d0e0f'
338
339 >>> # get the raw 16 bytes of the UUID
340 >>> x.bytes
341 b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
342
343 >>> # make a UUID from a 16-byte string
344 >>> uuid.UUID(bytes=x.bytes)
345 UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
346
347
348 .. _uuid-cli-example:
349
350 Command-Line Example
351 --------------------
352
353 Here are some examples of typical usage of the :mod:`uuid` command line interface:
354
355 .. code-block:: shell
356
357 # generate a random uuid - by default uuid4() is used
358 $ python -m uuid
359
360 # generate a uuid using uuid1()
361 $ python -m uuid -u uuid1
362
363 # generate a uuid using uuid5
364 $ python -m uuid -u uuid5 -n @url -N example.com
365