3726777f47ac4bba3e21b075905959bbea47e72eerikabeler"""UUID objects (universally unique identifiers) according to RFC 4122.
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleThis module provides immutable UUID objects (class UUID) and the functions
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleuuid1(), uuid3(), uuid4(), uuid5() for generating version 1, 3, 4, and 5
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleUUIDs as specified in RFC 4122.
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleIf all you want is a unique ID, you should probably call uuid1() or uuid4().
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleNote that uuid1() may compromise privacy since it creates a UUID containing
3726777f47ac4bba3e21b075905959bbea47e72eerikabelethe computer's network address. uuid4() creates a random UUID.
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleTypical usage:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> import uuid
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # make a UUID based on the host ID and current time
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> uuid.uuid1()
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # make a UUID using an MD5 hash of a namespace UUID and a name
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # make a random UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> uuid.uuid4()
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # make a UUID using a SHA-1 hash of a namespace UUID and a name
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # make a UUID from a string of hex digits (braces and hyphens ignored)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # convert a UUID to a string of hex digits in standard form
3726777f47ac4bba3e21b075905959bbea47e72eerikabele '00010203-0405-0607-0809-0a0b0c0d0e0f'
cbbae5f6f6dab2f4431c8609ef9aee6c00705645nd # get the raw 16 bytes of the UUID
cbbae5f6f6dab2f4431c8609ef9aee6c00705645nd >>> x.bytes
cbbae5f6f6dab2f4431c8609ef9aee6c00705645nd '\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
1fb92290c22cf761b7219074d75cde2016050ed1slive # make a UUID from a 16-byte string
d177004a74b061338daf7f2603197d673ed76d36kess >>> uuid.UUID(bytes=x.bytes)
43a46e566e58e888c7889448cabd3dcf1f4b9fbend UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
43a46e566e58e888c7889448cabd3dcf1f4b9fbendThis module works with Python 2.3 or higher."""
9a1b062f73a4a085af8fe41fae402aaee41d33ccnd__date__ = '$Date: 2009-08-25 14:31:43 +0200 (Tue, 25 Aug 2009) $'.split()[1].replace('/', '-')
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleRESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, RESERVED_FUTURE = [
3726777f47ac4bba3e21b075905959bbea47e72eerikabele 'reserved for NCS compatibility', 'specified in RFC 4122',
3726777f47ac4bba3e21b075905959bbea47e72eerikabele 'reserved for Microsoft compatibility', 'reserved for future definition']
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Instances of the UUID class represent UUIDs as specified in RFC 4122.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID objects are immutable, hashable, and usable as dictionary keys.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele Converting a UUID to a string with str() yields something in the form
3726777f47ac4bba3e21b075905959bbea47e72eerikabele '12345678-1234-1234-1234-123456789abc'. The UUID constructor accepts
3726777f47ac4bba3e21b075905959bbea47e72eerikabele four possible forms: a similar string of hexadecimal digits, or a
3726777f47ac4bba3e21b075905959bbea47e72eerikabele string of 16 raw bytes as an argument named 'bytes', or a tuple of
3726777f47ac4bba3e21b075905959bbea47e72eerikabele six integer fields (with 32-bit, 16-bit, 16-bit, 8-bit, 8-bit, and
3726777f47ac4bba3e21b075905959bbea47e72eerikabele 48-bit values respectively) as an argument named 'fields', or a single
3726777f47ac4bba3e21b075905959bbea47e72eerikabele 128-bit integer as an argument named 'int'.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUIDs have these read-only attributes:
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd bytes the UUID as a 16-byte string
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd fields a tuple of the six integer fields of the UUID,
3726777f47ac4bba3e21b075905959bbea47e72eerikabele which are also available as six individual attributes
3726777f47ac4bba3e21b075905959bbea47e72eerikabele and two derived attributes:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele time_low the first 32 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele time_mid the next 16 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele time_hi_version the next 16 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq_hi_variant the next 8 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq_low the next 8 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele node the last 48 bits of the UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele time the 60-bit timestamp
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq the 14-bit sequence number
3726777f47ac4bba3e21b075905959bbea47e72eerikabele hex the UUID as a 32-character hexadecimal string
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd int the UUID as a 128-bit integer
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd urn the UUID as a URN as specified in RFC 4122
eed750bc8c60b3057bf2f39a60866796260ee594slive variant the UUID variant (one of the constants RESERVED_NCS,
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd RFC_4122, RESERVED_MICROSOFT, or RESERVED_FUTURE)
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd version the UUID version number (1 through 5, meaningful only
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd when the variant is RFC_4122)
a6d007137e5f9daa1b188752a35b2146065e69bfslive def __init__(self, hex=None, bytes=None, fields=None, int=None,
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd r"""Create a UUID from either a string of 32 hexadecimal digits,
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd a string of 16 bytes as the 'bytes' argument, a tuple of six
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd integers (32-bit time_low, 16-bit time_mid, 16-bit time_hi_version,
7884a25869c5f99d815f7e2e9e42562ec532275dnd 8-bit clock_seq_hi_variant, 8-bit clock_seq_low, 48-bit node) as
7884a25869c5f99d815f7e2e9e42562ec532275dnd the 'fields' argument, or a single 128-bit integer as the 'int'
7884a25869c5f99d815f7e2e9e42562ec532275dnd argument. When a string of hex digits is given, curly braces,
d177004a74b061338daf7f2603197d673ed76d36kess hyphens, and a URN prefix are all optional. For example, these
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd expressions all yield the same UUID:
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd UUID('{12345678-1234-5678-1234-567812345678}')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('12345678123456781234567812345678')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID(bytes='\x12\x34\x56\x78'*4)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
3726777f47ac4bba3e21b075905959bbea47e72eerikabele UUID(int=0x12345678123456781234567812345678)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele Exactly one of 'hex', 'bytes', 'fields', or 'int' must be given.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele The 'version' argument is optional; if given, the resulting UUID
3726777f47ac4bba3e21b075905959bbea47e72eerikabele will have its variant and version number set according to RFC 4122,
3726777f47ac4bba3e21b075905959bbea47e72eerikabele overriding bits in the given 'hex', 'bytes', 'fields', or 'int'.
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd raise TypeError('need just one of hex, bytes, fields, or int')
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd if hex is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele hex = hex.replace('urn:', '').replace('uuid:', '')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele if bytes is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele int = long(('%02x'*16) % tuple(map(ord, bytes)), 16)
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd if fields is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq_hi_variant, clock_seq_low, node) = fields
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd raise ValueError('field 1 out of range (need a 32-bit value)')
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd raise ValueError('field 2 out of range (need a 16-bit value)')
480bee29abcc415b6b8c18d2ecbf2c5f88f1f05bnd raise ValueError('field 3 out of range (need a 16-bit value)')
480bee29abcc415b6b8c18d2ecbf2c5f88f1f05bnd raise ValueError('field 4 out of range (need an 8-bit value)')
480bee29abcc415b6b8c18d2ecbf2c5f88f1f05bnd raise ValueError('field 5 out of range (need an 8-bit value)')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele raise ValueError('field 6 out of range (need a 48-bit value)')
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq = (clock_seq_hi_variant << 8L) | clock_seq_low
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd if int is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele raise ValueError('int is out of range (need a 128-bit value)')
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd if version is not None:
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd # Set the variant to RFC 4122.
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd # Set the version number.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele return '%s-%s-%s-%s-%s' % (
3726777f47ac4bba3e21b075905959bbea47e72eerikabele hex[:8], hex[8:12], hex[12:16], hex[16:20], hex[20:])
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd return (self.time_low, self.time_mid, self.time_hi_version,
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd self.clock_seq_hi_variant, self.clock_seq_low, self.node)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq_hi_variant = property(get_clock_seq_hi_variant)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele return (((self.clock_seq_hi_variant & 0x3fL) << 8L) |
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # The version bits are only meaningful for RFC 4122 UUIDs.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Get the hardware address on Unix by running ifconfig."""
65241490e40aa0c831988073eed0633dad10c6f2nd """Get the hardware address on Windows by running ipconfig.exe."""
65241490e40aa0c831988073eed0633dad10c6f2nd dirs = ['', r'c:\windows\system32', r'c:\winnt\system32']
65241490e40aa0c831988073eed0633dad10c6f2nd if re.match('([0-9a-f][0-9a-f]-){5}[0-9a-f][0-9a-f]', value):
65241490e40aa0c831988073eed0633dad10c6f2nd """Get the hardware address on Windows using NetBIOS calls.
65241490e40aa0c831988073eed0633dad10c6f2nd See http://support.microsoft.com/kb/118623 for details."""
3726777f47ac4bba3e21b075905959bbea47e72eerikabele return ((bytes[0]<<40L) + (bytes[1]<<32L) + (bytes[2]<<24L) +
3726777f47ac4bba3e21b075905959bbea47e72eerikabele# Thanks to Thomas Heller for ctypes and for his help with its use here.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele# If ctypes is available, use it to find system routines for UUID generation.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele_uuid_generate_random = _uuid_generate_time = _UuidCreate = None
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd #import ctypes.util
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd # The uuid_generate_* routines are provided by libuuid on at least
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # Linux and FreeBSD, and provided by libc on Mac OS X.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele lib = ctypes.CDLL(ctypes.util.find_library(libname))
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # On Windows prior to 2000, UuidCreate gives a UUID containing the
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # hardware address. On Windows 2000 and later, UuidCreate makes a
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # random UUID and UuidCreateSequential gives a UUID containing the
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # hardware address. These routines are provided by the RPC runtime.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Get the hardware address on Unix using ctypes."""
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Get the hardware address on Windows using ctypes."""
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd """Get a random node ID, with eighth bit set as suggested by RFC 4122."""
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd """Get the hardware address as a 48-bit integer. The first time this
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd runs, it may launch a separate program, which could be quite slow. If
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd all attempts to obtain the hardware address fail, we choose a random
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd 48-bit number with its eighth bit set to 1 as recommended in RFC 4122."""
d3cd98e7839dd1c737c18d42a916ed20860a50e1nd if _node is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele getters = [_windll_getnode, _netbios_getnode, _ipconfig_getnode]
3726777f47ac4bba3e21b075905959bbea47e72eerikabele if _node is not None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Generate a UUID from a host ID, sequence number, and the current time.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele If 'node' is not given, getnode() is used to obtain the hardware
3726777f47ac4bba3e21b075905959bbea47e72eerikabele address. If 'clock_seq' is given, it is used as the sequence number;
3726777f47ac4bba3e21b075905959bbea47e72eerikabele otherwise a random 14-bit sequence number is chosen."""
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # When the system provides a version-1 UUID generator, use it (but don't
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # use UuidCreate here because its UUIDs don't conform to RFC 4122).
3726777f47ac4bba3e21b075905959bbea47e72eerikabele if _uuid_generate_time and node is clock_seq is None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # 0x01b21dd213814000 is the number of 100-ns intervals between the
d177004a74b061338daf7f2603197d673ed76d36kess # UUID epoch 1582-10-15 00:00:00 and the Unix epoch 1970-01-01 00:00:00.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele timestamp = int(nanoseconds/100) + 0x01b21dd213814000L
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq = random.randrange(1<<14L) # instead of stable storage
d177004a74b061338daf7f2603197d673ed76d36kess if node is None:
3726777f47ac4bba3e21b075905959bbea47e72eerikabele return UUID(fields=(time_low, time_mid, time_hi_version,
3726777f47ac4bba3e21b075905959bbea47e72eerikabele clock_seq_hi_variant, clock_seq_low, node), version=1)
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Generate a UUID from the MD5 hash of a namespace UUID and a name."""
3726777f47ac4bba3e21b075905959bbea47e72eerikabele """Generate a random UUID."""
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # When the system provides a version-4 UUID generator, use it.
3726777f47ac4bba3e21b075905959bbea47e72eerikabele # Otherwise, get randomness from urandom or the 'random' module.
094d4f190fd9e52804bcd5f620a6f0f817b127cdnd """Generate a UUID from the SHA-1 hash of a namespace UUID and a name."""
094d4f190fd9e52804bcd5f620a6f0f817b127cdnd# The following standard UUIDs are for use with uuid3() or uuid5().
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleNAMESPACE_DNS = UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8')
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleNAMESPACE_URL = UUID('6ba7b811-9dad-11d1-80b4-00c04fd430c8')
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleNAMESPACE_OID = UUID('6ba7b812-9dad-11d1-80b4-00c04fd430c8')
3726777f47ac4bba3e21b075905959bbea47e72eerikabeleNAMESPACE_X500 = UUID('6ba7b814-9dad-11d1-80b4-00c04fd430c8')