diff options
Diffstat (limited to 'Doc/lib/libuuid.tex')
| -rw-r--r-- | Doc/lib/libuuid.tex | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex new file mode 100644 index 0000000..a9d5295 --- /dev/null +++ b/Doc/lib/libuuid.tex @@ -0,0 +1,234 @@ +\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{, +fields\optional{, int\optional{, version}}}}}} + +%Instances of the UUID class represent UUIDs as specified in RFC 4122. +%UUID objects are immutable, hashable, and usable as dictionary keys. +%Converting a UUID to a string with str() yields something in the form +%'12345678-1234-1234-1234-123456789abc'. The UUID constructor accepts +%four possible forms: a similar string of hexadecimal digits, or a +%string of 16 raw bytes as an argument named 'bytes', or a tuple of +%six integer fields (with 32-bit, 16-bit, 16-bit, 8-bit, 8-bit, and +%48-bit values respectively) as an argument named 'fields', or a single +%128-bit integer as an argument named 'int'. + +Create a UUID from either a string of 32 hexadecimal digits, +a string of 16 bytes as the \var{bytes} 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(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) +UUID(int=0x12345678123456781234567812345678) +\end{verbatim} + +Exactly one of \var{hex}, \var{bytes}, \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{fields}, or \var{int}. + +\end{classdesc} + +\class{UUID} instances have these read-only attributes: + +\begin{memberdesc}{bytes} +The UUID as a 16-byte string. +\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 an integer equal to one of the 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 upon a MD5 hash of the \var{name} string value +drawn from a specified namespace. \var{namespace} +must be one of \constant{NAMESPACE_DNS}, +\constant{NAMESPACE_URL}, \constant{NAMESPACE_OID}, +or \constant{NAMESPACE_X500}. +\end{funcdesc} +\index{uuid3} + +\begin{funcdesc}{uuid4}{} +Generate a random UUID. +\end{funcdesc} +\index{uuid4} + +\begin{funcdesc}{uuid5}{namespace, name} +Generate a UUID based upon a SHA-1 hash of the \var{name} string value +drawn from a specified namespace. \var{namespace} +must be one of \constant{NAMESPACE_DNS}, +\constant{NAMESPACE_URL}, \constant{NAMESPACE_OID}, +or \constant{NAMESPACE_X500}. +\end{funcdesc} +\index{uuid5} + +The \module{uuid} module defines the following namespace constants +for use with \function{uuid3()} or \function{uuid5()}. + +\begin{datadesc}{NAMESPACE_DNS} +Fully-qualified domain name namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_URL} +URL namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_OID} +ISO OID namespace UUID. +\end{datadesc} + +\begin{datadesc}{NAMESPACE_X500} +X.500 DN namespace UUID. +\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} +Uses UUID layout specified in \rfc{4122}. +\end{datadesc} + +\begin{datadesc}{RESERVED_MICROSOFT} +Reserved for Microsoft backward 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 specifies a Uniform Resource Name namespace for UUIDs.} +\end{seealso} + +\subsection{Example \label{uuid-example}} + +Here is a typical usage: +\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} |