======================================
uuid -- Universally unique identifiers
======================================
.. module:: uuid
:synopsis: Universally unique identifiers
:Purpose: The :mod:`uuid` module implements Universally Unique Identifiers as described in :rfc:`4122`.
:Python Version: 2.5 and later
:rfc:`4122` defines a system for creating universally unique
identifiers for resources in a way that does not require a central
registrar. UUID values are 128 bits long and "can guarantee uniqueness
across space and time". They are useful for identifiers for documents,
hosts, application clients, and other situations where a unique value
is necessary. The RFC is specifically geared toward creating a Uniform
Resource Name namespace.
Three main algorithms are covered by the spec:
+ Using IEEE 802 MAC addresses as a source of uniqueness
+ Using pseudo-random numbers
+ Using well-known strings combined with cryptographic hashing
In all cases the seed value is combined with the system clock and a
clock sequence value (to maintain uniqueness in case the clock was set
backwards).
UUID 1 - IEEE 802 MAC Address
=============================
UUID version 1 values are computed using the MAC address of the host.
The :mod:`uuid` module uses :func:`getnode()` to retrieve the MAC
value on a given system:
.. include:: uuid_getnode.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_getnode.py'))
.. }}}
::
$ python uuid_getnode.py
0x1ec200d9e0
.. {{{end}}}
If a system has more than one network card, and so more than one MAC,
any one of the values may be returned.
To generate a UUID for a given host, identified by its MAC address,
use the :func:`uuid1()` function. You can pass a node identifier, or
leave the field blank to use the value returned by :func:`getnode()`.
.. include:: uuid_uuid1.py
:literal:
:start-after: #end_pymotw_header
The components of the UUID object returned can be accessed through
read-only instance attributes. Some attributes, such as *hex*, *int*,
and *urn*, are different representations of the UUID value.
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid1.py'))
.. }}}
::
$ python uuid_uuid1.py
098c95b3-df6e-11df-899a-001ec200d9e0
<class 'uuid.UUID'>
bytes : '\t\x8c\x95\xb3\xdfn\x11\xdf\x89\x9a\x00\x1e\xc2\x00\xd9\xe0'
hex : 098c95b3df6e11df899a001ec200d9e0
int : 12693009852279376310425064831178562016
urn : urn:uuid:098c95b3-df6e-11df-899a-001ec200d9e0
variant : specified in RFC 4122
version : 1
fields : (160208307L, 57198L, 4575L, 137L, 154L, 132103854560L)
time_low : 160208307
time_mid : 57198
time_hi_version : 4575
clock_seq_hi_variant: 137
clock_seq_low : 154
node : 132103854560
time : 135072177544009139
clock_seq : 2458
.. {{{end}}}
Because of the time component, each time :func:`uuid1()` is called a
new value is returned.
.. include:: uuid_uuid1_repeat.py
:literal:
:start-after: #end_pymotw_header
Notice in this output that only the time component (at the beginning
of the string) changes.
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid1_repeat.py'))
.. }}}
::
$ python uuid_uuid1_repeat.py
099b0e00-df6e-11df-9acd-001ec200d9e0
099cea35-df6e-11df-8121-001ec200d9e0
099cebcf-df6e-11df-bc49-001ec200d9e0
.. {{{end}}}
Because your computer has a different MAC address than mine, you will
see entirely different values if you run the examples, because the
node identifier at the end of the UUID will change, too.
.. include:: uuid_uuid1_othermac.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid1_othermac.py'))
.. }}}
::
$ python uuid_uuid1_othermac.py
0x1ec200d9e0 09af7551-df6e-11df-b2e2-001ec200d9e0
0x1e5274040e 09b00e5e-df6e-11df-a0c4-001e5274040e
.. {{{end}}}
UUID 3 and 5 - Name-Based Values
================================
It is also useful in some contexts to create UUID values from names
instead of random or time-based values. Versions 3 and 5 of the UUID
specification use cryptographic hash values (MD5 or SHA-1) to combine
namespace-specific seed values with "names" (DNS hostnames, URLs,
object ids, etc.). There are several well-known namespaces, identified
by pre-defined UUID values, for working with DNS, URLs, ISO OIDs, and
X.500 Distinguished Names. You can also define your own application-
specific namespaces by generating and saving UUID values.
To create a UUID from a DNS name, pass ``uuid.NAMESPACE_DNS`` as the
namespace argument to :func:`uuid3()` or :func:`uuid5()`:
.. include:: uuid_uuid3_uuid5.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid3_uuid5.py'))
.. }}}
::
$ python uuid_uuid3_uuid5.py
www.doughellmann.com
MD5 : bcd02e22-68f0-3046-a512-327cca9def8f
SHA-1 : e3329b12-30b7-57c4-8117-c2cd34a87ce9
blog.doughellmann.com
MD5 : 9bdabfce-dfd6-37ab-8a3f-7f7293bcf111
SHA-1 : fa829736-7ef8-5239-9906-b4775a5abacb
.. {{{end}}}
The UUID value for a given name in a namespace is always the same, no
matter when or where it is calculated. Values for the same name in
different namespaces are different.
.. include:: uuid_uuid3_repeat.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid3_repeat.py'))
.. }}}
::
$ python uuid_uuid3_repeat.py
bcd02e22-68f0-3046-a512-327cca9def8f
bcd02e22-68f0-3046-a512-327cca9def8f
bcd02e22-68f0-3046-a512-327cca9def8f
.. {{{end}}}
UUID 4 - Random Values
======================
Sometimes host-based and namespace-based UUID values are not
"different enough". For example, in cases where you want to use the
UUID as a lookup key, a more random sequence of values with more
differentiation is desirable to avoid collisions in a hash
table. Having values with fewer common digits also makes it easier to
find them in log files. To add greater differentiation in your UUIDs,
use :func:`uuid4()` to generate them using random input values.
.. include:: uuid_uuid4.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid4.py'))
.. }}}
::
$ python uuid_uuid4.py
05082f2e-6e12-4016-8b07-7970f9dcf9a7
60aae332-5119-40d0-9bb7-174e53454654
671bdeb2-fbee-458c-9b6f-55764054e635
.. {{{end}}}
Working with UUID Objects
=========================
In addition to generating new UUID values, you can parse strings in
various formats to create UUID objects. This makes it easier to
compare them, sort them, etc.
.. include:: uuid_uuid_objects.py
:literal:
:start-after: #end_pymotw_header
.. {{{cog
.. cog.out(run_script(cog.inFile, 'uuid_uuid_objects.py'))
.. }}}
::
$ python uuid_uuid_objects.py
input_values
urn:uuid:f2f84497-b3bf-493a-bba9-7c68e6def80b
{417a5ebb-01f7-4ed5-aeac-3d56cd5037b0}
2115773a-5bf1-11dd-ab48-001ec200d9e0
converted to uuids
f2f84497-b3bf-493a-bba9-7c68e6def80b
417a5ebb-01f7-4ed5-aeac-3d56cd5037b0
2115773a-5bf1-11dd-ab48-001ec200d9e0
sorted
2115773a-5bf1-11dd-ab48-001ec200d9e0
417a5ebb-01f7-4ed5-aeac-3d56cd5037b0
f2f84497-b3bf-493a-bba9-7c68e6def80b
.. {{{end}}}
.. seealso::
`uuid <http://docs.python.org/lib/module-uuid.html>`_
Standard library documentation for this module.
:rfc:`4122`
A Universally Unique IDentifier (UUID) URN Namespace