/Doc/library/uuid.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 258 lines · 157 code · 101 blank · 0 comment · 0 complexity · f4738441e60a8941602aed6947e67bb8 MD5 · raw file

  1. :mod:`uuid` --- UUID objects according to RFC 4122
  2. ==================================================
  3. .. module:: uuid
  4. :synopsis: UUID objects (universally unique identifiers) according to RFC 4122
  5. .. moduleauthor:: Ka-Ping Yee <ping@zesty.ca>
  6. .. sectionauthor:: George Yoshida <quiver@users.sourceforge.net>
  7. .. versionadded:: 2.5
  8. This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
  9. and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for
  10. generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`.
  11. If all you want is a unique ID, you should probably call :func:`uuid1` or
  12. :func:`uuid4`. Note that :func:`uuid1` may compromise privacy since it creates
  13. a UUID containing the computer's network address. :func:`uuid4` creates a
  14. random UUID.
  15. .. class:: UUID([hex[, bytes[, bytes_le[, fields[, int[, version]]]]]])
  16. Create a UUID from either a string of 32 hexadecimal digits, a string of 16
  17. bytes as the *bytes* argument, a string of 16 bytes in little-endian order as
  18. the *bytes_le* argument, a tuple of six integers (32-bit *time_low*, 16-bit
  19. *time_mid*, 16-bit *time_hi_version*, 8-bit *clock_seq_hi_variant*, 8-bit
  20. *clock_seq_low*, 48-bit *node*) as the *fields* argument, or a single 128-bit
  21. integer as the *int* argument. When a string of hex digits is given, curly
  22. braces, hyphens, and a URN prefix are all optional. For example, these
  23. expressions all yield the same UUID::
  24. UUID('{12345678-1234-5678-1234-567812345678}')
  25. UUID('12345678123456781234567812345678')
  26. UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
  27. UUID(bytes='\x12\x34\x56\x78'*4)
  28. UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' +
  29. '\x12\x34\x56\x78\x12\x34\x56\x78')
  30. UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
  31. UUID(int=0x12345678123456781234567812345678)
  32. Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must be given.
  33. The *version* argument is optional; if given, the resulting UUID will have its
  34. variant and version number set according to RFC 4122, overriding bits in the
  35. given *hex*, *bytes*, *bytes_le*, *fields*, or *int*.
  36. :class:`UUID` instances have these read-only attributes:
  37. .. attribute:: UUID.bytes
  38. The UUID as a 16-byte string (containing the six integer fields in big-endian
  39. byte order).
  40. .. attribute:: UUID.bytes_le
  41. The UUID as a 16-byte string (with *time_low*, *time_mid*, and *time_hi_version*
  42. in little-endian byte order).
  43. .. attribute:: UUID.fields
  44. A tuple of the six integer fields of the UUID, which are also available as six
  45. individual attributes and two derived attributes:
  46. +------------------------------+-------------------------------+
  47. | Field | Meaning |
  48. +==============================+===============================+
  49. | :attr:`time_low` | the first 32 bits of the UUID |
  50. +------------------------------+-------------------------------+
  51. | :attr:`time_mid` | the next 16 bits of the UUID |
  52. +------------------------------+-------------------------------+
  53. | :attr:`time_hi_version` | the next 16 bits of the UUID |
  54. +------------------------------+-------------------------------+
  55. | :attr:`clock_seq_hi_variant` | the next 8 bits of the UUID |
  56. +------------------------------+-------------------------------+
  57. | :attr:`clock_seq_low` | the next 8 bits of the UUID |
  58. +------------------------------+-------------------------------+
  59. | :attr:`node` | the last 48 bits of the UUID |
  60. +------------------------------+-------------------------------+
  61. | :attr:`time` | the 60-bit timestamp |
  62. +------------------------------+-------------------------------+
  63. | :attr:`clock_seq` | the 14-bit sequence number |
  64. +------------------------------+-------------------------------+
  65. .. attribute:: UUID.hex
  66. The UUID as a 32-character hexadecimal string.
  67. .. attribute:: UUID.int
  68. The UUID as a 128-bit integer.
  69. .. attribute:: UUID.urn
  70. The UUID as a URN as specified in RFC 4122.
  71. .. attribute:: UUID.variant
  72. The UUID variant, which determines the internal layout of the UUID. This will be
  73. one of the integer constants :const:`RESERVED_NCS`, :const:`RFC_4122`,
  74. :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`.
  75. .. attribute:: UUID.version
  76. The UUID version number (1 through 5, meaningful only when the variant is
  77. :const:`RFC_4122`).
  78. The :mod:`uuid` module defines the following functions:
  79. .. function:: getnode()
  80. Get the hardware address as a 48-bit positive integer. The first time this
  81. runs, it may launch a separate program, which could be quite slow. If all
  82. attempts to obtain the hardware address fail, we choose a random 48-bit number
  83. with its eighth bit set to 1 as recommended in RFC 4122. "Hardware address"
  84. means the MAC address of a network interface, and on a machine with multiple
  85. network interfaces the MAC address of any one of them may be returned.
  86. .. index:: single: getnode
  87. .. function:: uuid1([node[, clock_seq]])
  88. Generate a UUID from a host ID, sequence number, and the current time. If *node*
  89. is not given, :func:`getnode` is used to obtain the hardware address. If
  90. *clock_seq* is given, it is used as the sequence number; otherwise a random
  91. 14-bit sequence number is chosen.
  92. .. index:: single: uuid1
  93. .. function:: uuid3(namespace, name)
  94. Generate a UUID based on the MD5 hash of a namespace identifier (which is a
  95. UUID) and a name (which is a string).
  96. .. index:: single: uuid3
  97. .. function:: uuid4()
  98. Generate a random UUID.
  99. .. index:: single: uuid4
  100. .. function:: uuid5(namespace, name)
  101. Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
  102. UUID) and a name (which is a string).
  103. .. index:: single: uuid5
  104. The :mod:`uuid` module defines the following namespace identifiers for use with
  105. :func:`uuid3` or :func:`uuid5`.
  106. .. data:: NAMESPACE_DNS
  107. When this namespace is specified, the *name* string is a fully-qualified domain
  108. name.
  109. .. data:: NAMESPACE_URL
  110. When this namespace is specified, the *name* string is a URL.
  111. .. data:: NAMESPACE_OID
  112. When this namespace is specified, the *name* string is an ISO OID.
  113. .. data:: NAMESPACE_X500
  114. When this namespace is specified, the *name* string is an X.500 DN in DER or a
  115. text output format.
  116. The :mod:`uuid` module defines the following constants for the possible values
  117. of the :attr:`variant` attribute:
  118. .. data:: RESERVED_NCS
  119. Reserved for NCS compatibility.
  120. .. data:: RFC_4122
  121. Specifies the UUID layout given in :rfc:`4122`.
  122. .. data:: RESERVED_MICROSOFT
  123. Reserved for Microsoft compatibility.
  124. .. data:: RESERVED_FUTURE
  125. Reserved for future definition.
  126. .. seealso::
  127. :rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace
  128. This specification defines a Uniform Resource Name namespace for UUIDs, the
  129. internal format of UUIDs, and methods of generating UUIDs.
  130. .. _uuid-example:
  131. Example
  132. -------
  133. Here are some examples of typical usage of the :mod:`uuid` module::
  134. >>> import uuid
  135. # make a UUID based on the host ID and current time
  136. >>> uuid.uuid1()
  137. UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
  138. # make a UUID using an MD5 hash of a namespace UUID and a name
  139. >>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
  140. UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
  141. # make a random UUID
  142. >>> uuid.uuid4()
  143. UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
  144. # make a UUID using a SHA-1 hash of a namespace UUID and a name
  145. >>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
  146. UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
  147. # make a UUID from a string of hex digits (braces and hyphens ignored)
  148. >>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
  149. # convert a UUID to a string of hex digits in standard form
  150. >>> str(x)
  151. '00010203-0405-0607-0809-0a0b0c0d0e0f'
  152. # get the raw 16 bytes of the UUID
  153. >>> x.bytes
  154. '\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
  155. # make a UUID from a 16-byte string
  156. >>> uuid.UUID(bytes=x.bytes)
  157. UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')