uuid — 符合 RFC 9562 的 UUID 对象¶
源代码: Lib/uuid.py
此模块提供不可变的 UUID 对象（UUID 类）和 函数，用于生成符合 RFC 9562（它取代了 RFC 4122）中指定特定 UUID 版本的 UUID，例如，uuid1() 用于 UUID 版本 1，uuid3() 用于 UUID 版本 3，等等。请注意，UUID 版本 2 被有意省略，因为它超出了 RFC 的范围。
如果只需要一个唯一的 ID，则应调用 uuid1() 或 uuid4()。请注意，uuid1() 可能会损害隐私，因为它会创建一个包含计算机网络地址的 UUID。uuid4() 创建一个随机 UUID。
根据底层平台的支持，uuid1() 可能会或可能不会返回“安全”的 UUID。安全的 UUID 是使用同步方法生成的，这些方法确保没有两个进程可以获得相同的 UUID。UUID 的所有实例都有一个 is_safe 属性，它使用此枚举来传递有关 UUID 安全性的任何信息
- class uuid.SafeUUID¶
在 3.7 版本加入。
- safe¶
UUID 由平台以多进程安全的方式生成。
- unsafe¶
UUID 未以多进程安全的方式生成。
- unknown¶
平台不提供有关 UUID 是否安全生成的信息。
- class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)¶
通过 32 个十六进制数字字符串、以大端字节序排列的 16 字节字符串作为 bytes 参数、以小端字节序排列的 16 字节字符串作为 bytes_le 参数、六个整数的元组（32 位 time_low、16 位 time_mid、16 位 time_hi_version、8 位 clock_seq_hi_variant、8 位 clock_seq_low、48 位 node）作为 fields 参数，或者单个 128 位整数作为 int 参数来创建 UUID。当给定十六进制数字字符串时，花括号、连字符和 URN 前缀都是可选的。例如，这些表达式都生成相同的 UUID
UUID('{12345678-1234-5678-1234-567812345678}') UUID('12345678123456781234567812345678') UUID('urn:uuid:12345678-1234-5678-1234-567812345678') UUID(bytes=b'\x12\x34\x56\x78'*4) UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' + b'\x12\x34\x56\x78\x12\x34\x56\x78') UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) UUID(int=0x12345678123456781234567812345678)
hex、bytes、bytes_le、fields 或 int 中必须且只能指定一个。version 参数是可选的；如果给定，则结果 UUID 的变体和版本号将根据 RFC 9562 设置，覆盖给定 hex、bytes、bytes_le、fields 或 int 中的位。
UUID 对象的比较通过比较它们的
UUID.int属性进行。与非 UUID 对象的比较会引发TypeError。str(uuid)返回形式为12345678-1234-5678-1234-567812345678的字符串，其中 32 个十六进制数字表示 UUID。
UUID 实例具有以下只读属性
- UUID.bytes¶
UUID 作为 16 字节字符串（包含六个整数字段，以大端字节序排列）。
- UUID.bytes_le¶
UUID 作为 16 字节字符串（其中 time_low、time_mid 和 time_hi_version 以小端字节序排列）。
- UUID.fields¶
一个包含 UUID 六个整数字段的元组，这些字段也可用作六个单独的属性和两个派生属性
字段 |
含义 |
|
UUID 的前 32 位。仅与版本 1 相关。 |
|
UUID 的接下来的 16 位。仅与版本 1 相关。 |
|
UUID 的接下来的 16 位。仅与版本 1 相关。 |
|
UUID 的接下来的 8 位。仅与版本 1 和 6 相关。 |
|
UUID 的接下来的 8 位。仅与版本 1 和 6 相关。 |
|
UUID 的最后 48 位。仅与版本 1 相关。 |
|
对于版本 1 和 6，是自格里高利历纪元（1582-10-15 00:00:00）以来 100 纳秒间隔数的 60 位时间戳；对于版本 7，是自 Unix 纪元（1970-01-01 00:00:00）以来毫秒数的 48 位时间戳。 |
|
14 位序列号。仅与版本 1 和 6 相关。 |
- UUID.hex¶
UUID 作为 32 个字符的小写十六进制字符串。
- UUID.int¶
UUID 作为 128 位整数。
- UUID.variant¶
UUID 变体，它决定了 UUID 的内部布局。这将是常量
RESERVED_NCS、RFC_4122、RESERVED_MICROSOFT或RESERVED_FUTURE之一。
uuid 模块定义了以下函数
- uuid.getnode()¶
将硬件地址作为 48 位正整数获取。首次运行时，它可能会启动一个单独的程序，这可能会很慢。如果所有获取硬件地址的尝试都失败，我们将选择一个随机的 48 位数字，其中多播位（第一个八位字节的最低有效位）设置为 1，如 RFC 4122 中建议的那样。“硬件地址”是指网络接口的 MAC 地址。在具有多个网络接口的机器上，普遍管理的 MAC 地址（即第一个八位字节的倒数第二位未设置）将优于本地管理的 MAC 地址，但没有其他排序保证。
3.7 版本中的变化: 普遍管理的 MAC 地址优于本地管理的 MAC 地址，因为前者保证全局唯一，而后者不保证。
- uuid.uuid1(node=None, clock_seq=None)¶
根据 RFC 9562, §5.1 从主机 ID、序列号和当前时间生成 UUID。
未指定 node 时，使用
getnode()获取 48 位正整数的硬件地址。未指定序列号 clock_seq 时，生成一个伪随机的 14 位正整数。如果 node 或 clock_seq 超出其预期的位计数，则仅保留其最低有效位。
- uuid.uuid3(namespace, name)¶
根据 RFC 9562, §5.3，基于命名空间标识符（即 UUID）和名称（即
bytes对象或将使用 UTF-8 编码的字符串）的 MD5 散列生成 UUID。
- uuid.uuid4()¶
根据 RFC 9562, §5.4，以密码安全的方式生成随机 UUID。
- uuid.uuid5(namespace, name)¶
根据 RFC 9562, §5.5，基于命名空间标识符（即 UUID）和名称（即
bytes对象或将使用 UTF-8 编码的字符串）的 SHA-1 散列生成 UUID。
- uuid.uuid6(node=None, clock_seq=None)¶
根据 RFC 9562, §5.6 从序列号和当前时间生成 UUID。
这是
uuid1()的替代方案，用于改善数据库局部性。未指定 node 时，使用
getnode()获取 48 位正整数的硬件地址。未指定序列号 clock_seq 时，生成一个伪随机的 14 位正整数。如果 node 或 clock_seq 超出其预期的位计数，则仅保留其最低有效位。
在 3.14 版本加入。
- uuid.uuid7()¶
根据 RFC 9562, §5.7 生成基于时间的 UUID。
为了在缺乏亚毫秒精度的平台之间实现可移植性，此函数生成的 UUID 嵌入一个 48 位时间戳，并使用一个 42 位计数器来保证毫秒内的单调性。
在 3.14 版本加入。
- uuid.uuid8(a=None, b=None, c=None)¶
根据 RFC 9562, §5.8 生成伪随机 UUID。
指定时，参数 a、b 和 c 预期分别为 48 位、12 位和 62 位的正整数。如果它们超出其预期的位计数，则仅保留其最低有效位；未指定的参数将替换为适当大小的伪随机整数。
默认情况下，a、b 和 c 不是由密码安全伪随机数生成器 (CSPRNG) 生成的。当 UUID 需要在安全敏感上下文中使用时，请使用
uuid4()。在 3.14 版本加入。
uuid 模块定义了以下命名空间标识符，用于 uuid3() 或 uuid5()。
- uuid.NAMESPACE_DNS¶
指定此命名空间时，name 字符串是完全限定的域名。
- uuid.NAMESPACE_URL¶
指定此命名空间时，name 字符串是 URL。
- uuid.NAMESPACE_OID¶
指定此命名空间时，name 字符串是 ISO OID。
- uuid.NAMESPACE_X500¶
指定此命名空间时，name 字符串是 DER 或文本输出格式的 X.500 DN。
uuid 模块定义了以下常量，用于 variant 属性的可能值
- uuid.RESERVED_NCS¶
保留用于 NCS 兼容性。
- uuid.RESERVED_MICROSOFT¶
保留用于 Microsoft 兼容性。
- uuid.RESERVED_FUTURE¶
保留供将来定义。
uuid 模块定义了特殊的 Nil 和 Max UUID 值
- uuid.NIL¶
根据 RFC 9562, §5.9，一种特殊的 UUID 形式，其所有 128 位都设置为零。
在 3.14 版本加入。
- uuid.MAX¶
根据 RFC 9562, §5.10，一种特殊的 UUID 形式，其所有 128 位都设置为一。
在 3.14 版本加入。
参见
- RFC 9562 - 通用唯一标识符 (UUID) URN 命名空间
此规范定义了 UUID 的统一资源名称命名空间、UUID 的内部格式以及生成 UUID 的方法。
命令行用法¶
3.12 新版功能.
uuid 模块可以作为脚本从命令行执行。
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]
接受以下选项
- -h, --help¶
显示帮助信息并退出。
示例¶
以下是一些 uuid 模块的典型用法示例
>>> 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
b'\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')
>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')
>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')
>>> # same as UUIDv1 but with fields reordered to improve DB locality
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')
>>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
>>> u = uuid.uuid7()
>>> u.time
1743936859822
>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)
>>> # make a UUID with custom blocks
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')
命令行示例¶
以下是 uuid 命令行界面的典型用法示例
# generate a random UUID - by default uuid4() is used
$ python -m uuid
# generate a UUID using uuid1()
$ python -m uuid -u uuid1
# generate a UUID using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com
# generate 42 random UUIDs
$ python -m uuid -C 42