\section{\module{uuid} --- UUID objects according to RFC 4122}\declaremodule{builtin}{uuid}\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122}\moduleauthor{Ka-Ping Yee}{ping@zesty.ca}\sectionauthor{George Yoshida}{quiver@users.sourceforge.net} \versionadded{2.5} This module provides immutable \class{UUID} objects (the \class{UUID} class)and the functions \function{uuid1()}, \function{uuid3()},\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4,and 5 UUIDs as specified in \rfc{4122}. If all you want is a unique ID, you should probably call\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()}may compromise privacy since it creates a UUID containing the computer'snetwork address. \function{uuid4()} creates a random UUID. \begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{,bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}} Create a UUID from either a string of 32 hexadecimal digits,a string of 16 bytes as the \var{bytes} argument, a string of 16 bytesin little-endian order as the \var{bytes_le} argument, a tuple of sixintegers (32-bit \var{time_low}, 16-bit \var{time_mid},16-bit \var{time_hi_version},8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node})as the \var{fields} argument, or a single 128-bit integer as the \var{int}argument. When a string of hex digits is given, curly braces,hyphens, and a URN prefix are all optional. For example, theseexpressions all yield the same UUID: \begin{verbatim}UUID('{12345678-1234-5678-1234-567812345678}')UUID('12345678123456781234567812345678')UUID('urn:uuid:12345678-1234-5678-1234-567812345678')UUID(bytes='\x12\x34\x56\x78'*4)UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' + '\x12\x34\x56\x78\x12\x34\x56\x78')UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))UUID(int=0x12345678123456781234567812345678)\end{verbatim} Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields},or \var{int} mustbe given. The \var{version} argument is optional; if given, theresulting UUID will have its variant and version number set according toRFC 4122, overriding bits in the given \var{hex}, \var{bytes},\var{bytes_le}, \var{fields}, or \var{int}. \end{classdesc} \class{UUID} instances have these read-only attributes: \begin{memberdesc}{bytes}The UUID as a 16-byte string (containing the sixinteger fields in big-endian byte order).\end{memberdesc} \begin{memberdesc}{bytes_le}The UUID as a 16-byte string (with \var{time_low}, \var{time_mid},and \var{time_hi_version} in little-endian byte order).\end{memberdesc} \begin{memberdesc}{fields}A tuple of the six integer fields of the UUID, which are also availableas six individual attributes and two derived attributes: \begin{tableii}{l|l}{member}{Field}{Meaning} \lineii{time_low}{the first 32 bits of the UUID} \lineii{time_mid}{the next 16 bits of the UUID} \lineii{time_hi_version}{the next 16 bits of the UUID} \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID} \lineii{clock_seq_low}{the next 8 bits of the UUID} \lineii{node}{the last 48 bits of the UUID} \lineii{time}{the 60-bit timestamp} \lineii{clock_seq}{the 14-bit sequence number}\end{tableii} \end{memberdesc} \begin{memberdesc}{hex}The UUID as a 32-character hexadecimal string.\end{memberdesc} \begin{memberdesc}{int}The UUID as a 128-bit integer.\end{memberdesc} \begin{memberdesc}{urn}The UUID as a URN as specified in RFC 4122.\end{memberdesc} \begin{memberdesc}{variant}The UUID variant, which determines the internal layout of the UUID.This will be one of the integer constants\constant{RESERVED_NCS},\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or\constant{RESERVED_FUTURE}.\end{memberdesc} \begin{memberdesc}{version}The UUID version number (1 through 5, meaningful onlywhen the variant is \constant{RFC_4122}).\end{memberdesc} The \module{uuid} module defines the following functions: \begin{funcdesc}{getnode}{}Get the hardware address as a 48-bit positive integer. The first time thisruns, it may launch a separate program, which could be quite slow. If allattempts to obtain the hardware address fail, we choose a random 48-bitnumber with its eighth bit set to 1 as recommended in RFC 4122. "Hardwareaddress" means the MAC address of a network interface, and on a machinewith multiple network interfaces the MAC address of any one of them maybe returned.\end{funcdesc}\index{getnode} \begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}}Generate a UUID from a host ID, sequence number, and the current time.If \var{node} is not given, \function{getnode()} is used to obtain thehardware address.If \var{clock_seq} is given, it is used as the sequence number;otherwise a random 14-bit sequence number is chosen.\end{funcdesc}\index{uuid1} \begin{funcdesc}{uuid3}{namespace, name}Generate a UUID based on the MD5 hashof a namespace identifier (which is a UUID) and a name (which is a string).\end{funcdesc}\index{uuid3} \begin{funcdesc}{uuid4}{}Generate a random UUID.\end{funcdesc}\index{uuid4} \begin{funcdesc}{uuid5}{namespace, name}Generate a UUID based on the SHA-1 hashof a namespace identifier (which is a UUID) and a name (which is a string).\end{funcdesc}\index{uuid5} The \module{uuid} module defines the following namespace identifiersfor use with \function{uuid3()} or \function{uuid5()}. \begin{datadesc}{NAMESPACE_DNS}When this namespace is specified,the \var{name} string is a fully-qualified domain name.\end{datadesc} \begin{datadesc}{NAMESPACE_URL}When this namespace is specified,the \var{name} string is a URL.\end{datadesc} \begin{datadesc}{NAMESPACE_OID}When this namespace is specified,the \var{name} string is an ISO OID.\end{datadesc} \begin{datadesc}{NAMESPACE_X500}When this namespace is specified,the \var{name} string is an X.500 DN in DER or a text output format.\end{datadesc} The \module{uuid} module defines the following constantsfor the possible values of the \member{variant} attribute: \begin{datadesc}{RESERVED_NCS}Reserved for NCS compatibility.\end{datadesc} \begin{datadesc}{RFC_4122}Specifies the UUID layout given in \rfc{4122}.\end{datadesc} \begin{datadesc}{RESERVED_MICROSOFT}Reserved for Microsoft compatibility.\end{datadesc} \begin{datadesc}{RESERVED_FUTURE}Reserved for future definition.\end{datadesc} \begin{seealso} \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{This specification defines a Uniform Resource Name namespace for UUIDs,the internal format of UUIDs, and methods of generating UUIDs.}\end{seealso} \subsection{Example \label{uuid-example}} Here are some examples of typical usage of the \module{uuid} module:\begin{verbatim}>>> import uuid # make a UUID based on the host ID and current time>>> uuid.uuid1()UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') # make a UUID using an MD5 hash of a namespace UUID and a name>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') # make a random UUID>>> uuid.uuid4()UUID('16fd2706-8baf-433b-82eb-8c7fada847da') # make a UUID using a SHA-1 hash of a namespace UUID and a name>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') # make a UUID from a string of hex digits (braces and hyphens ignored)>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') # convert a UUID to a string of hex digits in standard form>>> str(x)'00010203-0405-0607-0809-0a0b0c0d0e0f' # get the raw 16 bytes of the UUID>>> x.bytes'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' # make a UUID from a 16-byte string>>> uuid.UUID(bytes=x.bytes)UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')\end{verbatim}
\section{\module{uuid} ---
UUID objects according to RFC 4122}
\declaremodule{builtin}{uuid}
\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122}
\moduleauthor{Ka-Ping Yee}{ping@zesty.ca}
\sectionauthor{George Yoshida}{quiver@users.sourceforge.net}
\versionadded{2.5}
This module provides immutable \class{UUID} objects (the \class{UUID} class)
and the functions \function{uuid1()}, \function{uuid3()},
\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4,
and 5 UUIDs as specified in \rfc{4122}.
If all you want is a unique ID, you should probably call
\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()}
may compromise privacy since it creates a UUID containing the computer's
network address. \function{uuid4()} creates a random UUID.
\begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{,
bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}}
Create a UUID from either a string of 32 hexadecimal digits,
a string of 16 bytes as the \var{bytes} argument, a string of 16 bytes
in little-endian order as the \var{bytes_le} argument, a tuple of six
integers (32-bit \var{time_low}, 16-bit \var{time_mid},
16-bit \var{time_hi_version},
8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node})
as the \var{fields} argument, or a single 128-bit integer as the \var{int}
argument. When a string of hex digits is given, curly braces,
hyphens, and a URN prefix are all optional. For example, these
expressions all yield the same UUID:
\begin{verbatim}
UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes='\x12\x34\x56\x78'*4)
UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' +
'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)
\end{verbatim}
Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields},
or \var{int} must
be given. The \var{version} argument is optional; if given, the
resulting UUID will have its variant and version number set according to
RFC 4122, overriding bits in the given \var{hex}, \var{bytes},
\var{bytes_le}, \var{fields}, or \var{int}.
\end{classdesc}
\class{UUID} instances have these read-only attributes:
\begin{memberdesc}{bytes}
The UUID as a 16-byte string (containing the six
integer fields in big-endian byte order).
\end{memberdesc}
\begin{memberdesc}{bytes_le}
The UUID as a 16-byte string (with \var{time_low}, \var{time_mid},
and \var{time_hi_version} in little-endian byte order).
\end{memberdesc}
\begin{memberdesc}{fields}
A tuple of the six integer fields of the UUID, which are also available
as six individual attributes and two derived attributes:
\begin{tableii}{l|l}{member}{Field}{Meaning}
\lineii{time_low}{the first 32 bits of the UUID}
\lineii{time_mid}{the next 16 bits of the UUID}
\lineii{time_hi_version}{the next 16 bits of the UUID}
\lineii{clock_seq_hi_variant}{the next 8 bits of the UUID}
\lineii{clock_seq_low}{the next 8 bits of the UUID}
\lineii{node}{the last 48 bits of the UUID}
\lineii{time}{the 60-bit timestamp}
\lineii{clock_seq}{the 14-bit sequence number}
\end{tableii}
\end{memberdesc}
\begin{memberdesc}{hex}
The UUID as a 32-character hexadecimal string.
\end{memberdesc}
\begin{memberdesc}{int}
The UUID as a 128-bit integer.
\end{memberdesc}
\begin{memberdesc}{urn}
The UUID as a URN as specified in RFC 4122.
\end{memberdesc}
\begin{memberdesc}{variant}
The UUID variant, which determines the internal layout of the UUID.
This will be one of the integer constants
\constant{RESERVED_NCS},
\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or
\constant{RESERVED_FUTURE}.
\end{memberdesc}
\begin{memberdesc}{version}
The UUID version number (1 through 5, meaningful only
when the variant is \constant{RFC_4122}).
\end{memberdesc}
The \module{uuid} module defines the following functions:
\begin{funcdesc}{getnode}{}
Get the hardware address as a 48-bit positive integer. The first time this
runs, it may launch a separate program, which could be quite slow. If all
attempts to obtain the hardware address fail, we choose a random 48-bit
number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware
address" means the MAC address of a network interface, and on a machine
with multiple network interfaces the MAC address of any one of them may
be returned.
\end{funcdesc}
\index{getnode}
\begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}}
Generate a UUID from a host ID, sequence number, and the current time.
If \var{node} is not given, \function{getnode()} is used to obtain the
hardware address.
If \var{clock_seq} is given, it is used as the sequence number;
otherwise a random 14-bit sequence number is chosen.
\end{funcdesc}
\index{uuid1}
\begin{funcdesc}{uuid3}{namespace, name}
Generate a UUID based on the MD5 hash
of a namespace identifier (which is a UUID) and a name (which is a string).
\end{funcdesc}
\index{uuid3}
\begin{funcdesc}{uuid4}{}
Generate a random UUID.
\end{funcdesc}
\index{uuid4}
\begin{funcdesc}{uuid5}{namespace, name}
Generate a UUID based on the SHA-1 hash
of a namespace identifier (which is a UUID) and a name (which is a string).
\end{funcdesc}
\index{uuid5}
The \module{uuid} module defines the following namespace identifiers
for use with \function{uuid3()} or \function{uuid5()}.
\begin{datadesc}{NAMESPACE_DNS}
When this namespace is specified,
the \var{name} string is a fully-qualified domain name.
\end{datadesc}
\begin{datadesc}{NAMESPACE_URL}
When this namespace is specified,
the \var{name} string is a URL.
\end{datadesc}
\begin{datadesc}{NAMESPACE_OID}
When this namespace is specified,
the \var{name} string is an ISO OID.
\end{datadesc}
\begin{datadesc}{NAMESPACE_X500}
When this namespace is specified,
the \var{name} string is an X.500 DN in DER or a text output format.
\end{datadesc}
The \module{uuid} module defines the following constants
for the possible values of the \member{variant} attribute:
\begin{datadesc}{RESERVED_NCS}
Reserved for NCS compatibility.
\end{datadesc}
\begin{datadesc}{RFC_4122}
Specifies the UUID layout given in \rfc{4122}.
\end{datadesc}
\begin{datadesc}{RESERVED_MICROSOFT}
Reserved for Microsoft compatibility.
\end{datadesc}
\begin{datadesc}{RESERVED_FUTURE}
Reserved for future definition.
\end{datadesc}
\begin{seealso}
\seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{
This specification defines a Uniform Resource Name namespace for UUIDs,
the internal format of UUIDs, and methods of generating UUIDs.}
\end{seealso}
\subsection{Example \label{uuid-example}}
Here are some examples of typical usage of the \module{uuid} module:
\begin{verbatim}
>>> import uuid
# make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
# make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
# make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
# make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
# make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
# convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'
# get the raw 16 bytes of the UUID
>>> x.bytes
'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
# make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
\end{verbatim}