[Bug #1508766] Add docs for uuid module; docs written by George Yoshida, with minor rearrangements by me.
This commit is contained in:
parent
d77ef8fa51
commit
146d3924b0
|
@ -0,0 +1,231 @@
|
|||
\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 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.
|
||||
\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}
|
Loading…
Reference in New Issue