diff options
Diffstat (limited to 'Doc/lib/libuuid.tex')
| -rw-r--r-- | Doc/lib/libuuid.tex | 233 |
1 files changed, 0 insertions, 233 deletions
diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex deleted file mode 100644 index 5aa9d8c..0000000 --- a/Doc/lib/libuuid.tex +++ /dev/null @@ -1,233 +0,0 @@ -\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} |