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:`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   +------------------------------+-------------------------------+
99   | Field                        | Meaning                       |
100   +==============================+===============================+
101   | :attr:`time_low`             | the first 32 bits of the UUID |
102   +------------------------------+-------------------------------+
103   | :attr:`time_mid`             | the next 16 bits of the UUID  |
104   +------------------------------+-------------------------------+
105   | :attr:`time_hi_version`      | the next 16 bits of the UUID  |
106   +------------------------------+-------------------------------+
107   | :attr:`clock_seq_hi_variant` | the next 8 bits of the UUID   |
108   +------------------------------+-------------------------------+
109   | :attr:`clock_seq_low`        | the next 8 bits of the UUID   |
110   +------------------------------+-------------------------------+
111   | :attr:`node`                 | the last 48 bits of the UUID  |
112   +------------------------------+-------------------------------+
113   | :attr:`time`                 | the 60-bit timestamp          |
114   +------------------------------+-------------------------------+
115   | :attr:`clock_seq`            | the 14-bit sequence number    |
116   +------------------------------+-------------------------------+
117
118
119.. attribute:: UUID.hex
120
121   The UUID as a 32-character hexadecimal string.
122
123
124.. attribute:: UUID.int
125
126   The UUID as a 128-bit integer.
127
128
129.. attribute:: UUID.urn
130
131   The UUID as a URN as specified in :rfc:`4122`.
132
133
134.. attribute:: UUID.variant
135
136   The UUID variant, which determines the internal layout of the UUID. This will be
137   one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`,
138   :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`.
139
140
141.. attribute:: UUID.version
142
143   The UUID version number (1 through 5, meaningful only when the variant is
144   :const:`RFC_4122`).
145
146.. attribute:: UUID.is_safe
147
148   An enumeration of :class:`SafeUUID` which indicates whether the platform
149   generated the UUID in a multiprocessing-safe way.
150
151   .. versionadded:: 3.7
152
153The :mod:`uuid` module defines the following functions:
154
155
156.. function:: getnode()
157
158   Get the hardware address as a 48-bit positive integer.  The first time this
159   runs, it may launch a separate program, which could be quite slow.  If all
160   attempts to obtain the hardware address fail, we choose a random 48-bit
161   number with the multicast bit (least significant bit of the first octet)
162   set to 1 as recommended in :rfc:`4122`.  "Hardware address" means the MAC
163   address of a network interface.  On a machine with multiple network
164   interfaces, universally administered MAC addresses (i.e. where the second
165   least significant bit of the first octet is *unset*) will be preferred over
166   locally administered MAC addresses, but with no other ordering guarantees.
167
168   .. versionchanged:: 3.7
169      Universally administered MAC addresses are preferred over locally
170      administered MAC addresses, since the former are guaranteed to be
171      globally unique, while the latter are not.
172
173.. index:: single: getnode
174
175
176.. function:: uuid1(node=None, clock_seq=None)
177
178   Generate a UUID from a host ID, sequence number, and the current time. If *node*
179   is not given, :func:`getnode` is used to obtain the hardware address. If
180   *clock_seq* is given, it is used as the sequence number; otherwise a random
181   14-bit sequence number is chosen.
182
183.. index:: single: uuid1
184
185
186.. function:: uuid3(namespace, name)
187
188   Generate a UUID based on the MD5 hash of a namespace identifier (which is a
189   UUID) and a name (which is a string).
190
191.. index:: single: uuid3
192
193
194.. function:: uuid4()
195
196   Generate a random UUID.
197
198.. index:: single: uuid4
199
200
201.. function:: uuid5(namespace, name)
202
203   Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
204   UUID) and a name (which is a string).
205
206.. index:: single: uuid5
207
208The :mod:`uuid` module defines the following namespace identifiers for use with
209:func:`uuid3` or :func:`uuid5`.
210
211
212.. data:: NAMESPACE_DNS
213
214   When this namespace is specified, the *name* string is a fully-qualified domain
215   name.
216
217
218.. data:: NAMESPACE_URL
219
220   When this namespace is specified, the *name* string is a URL.
221
222
223.. data:: NAMESPACE_OID
224
225   When this namespace is specified, the *name* string is an ISO OID.
226
227
228.. data:: NAMESPACE_X500
229
230   When this namespace is specified, the *name* string is an X.500 DN in DER or a
231   text output format.
232
233The :mod:`uuid` module defines the following constants for the possible values
234of the :attr:`variant` attribute:
235
236
237.. data:: RESERVED_NCS
238
239   Reserved for NCS compatibility.
240
241
242.. data:: RFC_4122
243
244   Specifies the UUID layout given in :rfc:`4122`.
245
246
247.. data:: RESERVED_MICROSOFT
248
249   Reserved for Microsoft compatibility.
250
251
252.. data:: RESERVED_FUTURE
253
254   Reserved for future definition.
255
256
257.. seealso::
258
259   :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace
260      This specification defines a Uniform Resource Name namespace for UUIDs, the
261      internal format of UUIDs, and methods of generating UUIDs.
262
263
264.. _uuid-example:
265
266Example
267-------
268
269Here are some examples of typical usage of the :mod:`uuid` module::
270
271   >>> import uuid
272
273   >>> # make a UUID based on the host ID and current time
274   >>> uuid.uuid1()
275   UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
276
277   >>> # make a UUID using an MD5 hash of a namespace UUID and a name
278   >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
279   UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
280
281   >>> # make a random UUID
282   >>> uuid.uuid4()
283   UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
284
285   >>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
286   >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
287   UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
288
289   >>> # make a UUID from a string of hex digits (braces and hyphens ignored)
290   >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
291
292   >>> # convert a UUID to a string of hex digits in standard form
293   >>> str(x)
294   '00010203-0405-0607-0809-0a0b0c0d0e0f'
295
296   >>> # get the raw 16 bytes of the UUID
297   >>> x.bytes
298   b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
299
300   >>> # make a UUID from a 16-byte string
301   >>> uuid.UUID(bytes=x.bytes)
302   UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
303
304