Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 1 | \section{\module{uuid} --- |
| 2 | UUID objects according to RFC 4122} |
| 3 | \declaremodule{builtin}{uuid} |
| 4 | \modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122} |
| 5 | \moduleauthor{Ka-Ping Yee}{ping@zesty.ca} |
| 6 | \sectionauthor{George Yoshida}{quiver@users.sourceforge.net} |
| 7 | |
| 8 | \versionadded{2.5} |
| 9 | |
| 10 | This module provides immutable \class{UUID} objects (the \class{UUID} class) |
| 11 | and the functions \function{uuid1()}, \function{uuid3()}, |
| 12 | \function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4, |
| 13 | and 5 UUIDs as specified in \rfc{4122}. |
| 14 | |
| 15 | If all you want is a unique ID, you should probably call |
| 16 | \function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()} |
| 17 | may compromise privacy since it creates a UUID containing the computer's |
| 18 | network address. \function{uuid4()} creates a random UUID. |
| 19 | |
| 20 | \begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{, |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 21 | bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}} |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 22 | |
| 23 | Create a UUID from either a string of 32 hexadecimal digits, |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 24 | a string of 16 bytes as the \var{bytes} argument, a string of 16 bytes |
| 25 | in little-endian order as the \var{bytes_le} argument, a tuple of six |
Tim Peters | 750c442 | 2006-07-28 04:51:59 +0000 | [diff] [blame] | 26 | integers (32-bit \var{time_low}, 16-bit \var{time_mid}, |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 27 | 16-bit \var{time_hi_version}, |
| 28 | 8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node}) |
| 29 | as the \var{fields} argument, or a single 128-bit integer as the \var{int} |
| 30 | argument. When a string of hex digits is given, curly braces, |
| 31 | hyphens, and a URN prefix are all optional. For example, these |
| 32 | expressions all yield the same UUID: |
| 33 | |
| 34 | \begin{verbatim} |
| 35 | UUID('{12345678-1234-5678-1234-567812345678}') |
| 36 | UUID('12345678123456781234567812345678') |
| 37 | UUID('urn:uuid:12345678-1234-5678-1234-567812345678') |
| 38 | UUID(bytes='\x12\x34\x56\x78'*4) |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 39 | UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' + |
| 40 | '\x12\x34\x56\x78\x12\x34\x56\x78') |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 41 | UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) |
| 42 | UUID(int=0x12345678123456781234567812345678) |
| 43 | \end{verbatim} |
| 44 | |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 45 | Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields}, |
| 46 | or \var{int} must |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 47 | be given. The \var{version} argument is optional; if given, the |
| 48 | resulting UUID will have its variant and version number set according to |
| 49 | RFC 4122, overriding bits in the given \var{hex}, \var{bytes}, |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 50 | \var{bytes_le}, \var{fields}, or \var{int}. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 51 | |
| 52 | \end{classdesc} |
| 53 | |
| 54 | \class{UUID} instances have these read-only attributes: |
| 55 | |
| 56 | \begin{memberdesc}{bytes} |
Anthony Baxter | ab7e5ef | 2006-08-22 07:36:06 +0000 | [diff] [blame] | 57 | The UUID as a 16-byte string (containing the six |
| 58 | integer fields in big-endian byte order). |
| 59 | \end{memberdesc} |
| 60 | |
| 61 | \begin{memberdesc}{bytes_le} |
| 62 | The UUID as a 16-byte string (with \var{time_low}, \var{time_mid}, |
| 63 | and \var{time_hi_version} in little-endian byte order). |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 64 | \end{memberdesc} |
| 65 | |
| 66 | \begin{memberdesc}{fields} |
| 67 | A tuple of the six integer fields of the UUID, which are also available |
| 68 | as six individual attributes and two derived attributes: |
| 69 | |
| 70 | \begin{tableii}{l|l}{member}{Field}{Meaning} |
| 71 | \lineii{time_low}{the first 32 bits of the UUID} |
| 72 | \lineii{time_mid}{the next 16 bits of the UUID} |
| 73 | \lineii{time_hi_version}{the next 16 bits of the UUID} |
| 74 | \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID} |
| 75 | \lineii{clock_seq_low}{the next 8 bits of the UUID} |
| 76 | \lineii{node}{the last 48 bits of the UUID} |
| 77 | \lineii{time}{the 60-bit timestamp} |
| 78 | \lineii{clock_seq}{the 14-bit sequence number} |
| 79 | \end{tableii} |
| 80 | |
| 81 | |
| 82 | \end{memberdesc} |
| 83 | |
| 84 | \begin{memberdesc}{hex} |
| 85 | The UUID as a 32-character hexadecimal string. |
| 86 | \end{memberdesc} |
| 87 | |
| 88 | \begin{memberdesc}{int} |
| 89 | The UUID as a 128-bit integer. |
| 90 | \end{memberdesc} |
| 91 | |
| 92 | \begin{memberdesc}{urn} |
| 93 | The UUID as a URN as specified in RFC 4122. |
| 94 | \end{memberdesc} |
| 95 | |
| 96 | \begin{memberdesc}{variant} |
| 97 | The UUID variant, which determines the internal layout of the UUID. |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 98 | This will be one of the integer constants |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 99 | \constant{RESERVED_NCS}, |
| 100 | \constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 101 | \constant{RESERVED_FUTURE}. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 102 | \end{memberdesc} |
| 103 | |
| 104 | \begin{memberdesc}{version} |
| 105 | The UUID version number (1 through 5, meaningful only |
| 106 | when the variant is \constant{RFC_4122}). |
| 107 | \end{memberdesc} |
| 108 | |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 109 | The \module{uuid} module defines the following functions: |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 110 | |
| 111 | \begin{funcdesc}{getnode}{} |
Tim Peters | 750c442 | 2006-07-28 04:51:59 +0000 | [diff] [blame] | 112 | Get the hardware address as a 48-bit positive integer. The first time this |
| 113 | runs, it may launch a separate program, which could be quite slow. If all |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 114 | attempts to obtain the hardware address fail, we choose a random 48-bit |
Tim Peters | 750c442 | 2006-07-28 04:51:59 +0000 | [diff] [blame] | 115 | number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware |
| 116 | address" means the MAC address of a network interface, and on a machine |
| 117 | with multiple network interfaces the MAC address of any one of them may |
| 118 | be returned. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 119 | \end{funcdesc} |
| 120 | \index{getnode} |
| 121 | |
| 122 | \begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}} |
| 123 | Generate a UUID from a host ID, sequence number, and the current time. |
| 124 | If \var{node} is not given, \function{getnode()} is used to obtain the |
| 125 | hardware address. |
| 126 | If \var{clock_seq} is given, it is used as the sequence number; |
| 127 | otherwise a random 14-bit sequence number is chosen. |
| 128 | \end{funcdesc} |
| 129 | \index{uuid1} |
| 130 | |
| 131 | \begin{funcdesc}{uuid3}{namespace, name} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 132 | Generate a UUID based on the MD5 hash |
| 133 | of a namespace identifier (which is a UUID) and a name (which is a string). |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 134 | \end{funcdesc} |
| 135 | \index{uuid3} |
| 136 | |
| 137 | \begin{funcdesc}{uuid4}{} |
| 138 | Generate a random UUID. |
| 139 | \end{funcdesc} |
| 140 | \index{uuid4} |
| 141 | |
| 142 | \begin{funcdesc}{uuid5}{namespace, name} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 143 | Generate a UUID based on the SHA-1 hash |
| 144 | of a namespace identifier (which is a UUID) and a name (which is a string). |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 145 | \end{funcdesc} |
| 146 | \index{uuid5} |
| 147 | |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 148 | The \module{uuid} module defines the following namespace identifiers |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 149 | for use with \function{uuid3()} or \function{uuid5()}. |
| 150 | |
| 151 | \begin{datadesc}{NAMESPACE_DNS} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 152 | When this namespace is specified, |
| 153 | the \var{name} string is a fully-qualified domain name. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 154 | \end{datadesc} |
| 155 | |
| 156 | \begin{datadesc}{NAMESPACE_URL} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 157 | When this namespace is specified, |
| 158 | the \var{name} string is a URL. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 159 | \end{datadesc} |
| 160 | |
| 161 | \begin{datadesc}{NAMESPACE_OID} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 162 | When this namespace is specified, |
| 163 | the \var{name} string is an ISO OID. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 164 | \end{datadesc} |
| 165 | |
| 166 | \begin{datadesc}{NAMESPACE_X500} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 167 | When this namespace is specified, |
| 168 | the \var{name} string is an X.500 DN in DER or a text output format. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 169 | \end{datadesc} |
| 170 | |
Tim Peters | 750c442 | 2006-07-28 04:51:59 +0000 | [diff] [blame] | 171 | The \module{uuid} module defines the following constants |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 172 | for the possible values of the \member{variant} attribute: |
| 173 | |
| 174 | \begin{datadesc}{RESERVED_NCS} |
| 175 | Reserved for NCS compatibility. |
| 176 | \end{datadesc} |
| 177 | |
| 178 | \begin{datadesc}{RFC_4122} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 179 | Specifies the UUID layout given in \rfc{4122}. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 180 | \end{datadesc} |
| 181 | |
| 182 | \begin{datadesc}{RESERVED_MICROSOFT} |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 183 | Reserved for Microsoft compatibility. |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 184 | \end{datadesc} |
| 185 | |
| 186 | \begin{datadesc}{RESERVED_FUTURE} |
| 187 | Reserved for future definition. |
| 188 | \end{datadesc} |
| 189 | |
| 190 | |
| 191 | \begin{seealso} |
| 192 | \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{ |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 193 | This specification defines a Uniform Resource Name namespace for UUIDs, |
| 194 | the internal format of UUIDs, and methods of generating UUIDs.} |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 195 | \end{seealso} |
| 196 | |
| 197 | \subsection{Example \label{uuid-example}} |
| 198 | |
Georg Brandl | 77aad9a | 2006-09-15 05:26:17 +0000 | [diff] [blame] | 199 | Here are some examples of typical usage of the \module{uuid} module: |
Andrew M. Kuchling | 146d392 | 2006-06-28 14:25:20 +0000 | [diff] [blame] | 200 | \begin{verbatim} |
| 201 | >>> import uuid |
| 202 | |
| 203 | # make a UUID based on the host ID and current time |
| 204 | >>> uuid.uuid1() |
| 205 | UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') |
| 206 | |
| 207 | # make a UUID using an MD5 hash of a namespace UUID and a name |
| 208 | >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') |
| 209 | UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') |
| 210 | |
| 211 | # make a random UUID |
| 212 | >>> uuid.uuid4() |
| 213 | UUID('16fd2706-8baf-433b-82eb-8c7fada847da') |
| 214 | |
| 215 | # make a UUID using a SHA-1 hash of a namespace UUID and a name |
| 216 | >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') |
| 217 | UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') |
| 218 | |
| 219 | # make a UUID from a string of hex digits (braces and hyphens ignored) |
| 220 | >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') |
| 221 | |
| 222 | # convert a UUID to a string of hex digits in standard form |
| 223 | >>> str(x) |
| 224 | '00010203-0405-0607-0809-0a0b0c0d0e0f' |
| 225 | |
| 226 | # get the raw 16 bytes of the UUID |
| 227 | >>> x.bytes |
| 228 | '\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' |
| 229 | |
| 230 | # make a UUID from a 16-byte string |
| 231 | >>> uuid.UUID(bytes=x.bytes) |
| 232 | UUID('00010203-0405-0607-0809-0a0b0c0d0e0f') |
| 233 | \end{verbatim} |