uuid --- UUID objects according to RFC 9562¶
原始碼：Lib/uuid.py
This module provides immutable UUID objects (the UUID class)
and functions for generating UUIDs corresponding
to a specific UUID version as specified in RFC 9562 (which supersedes RFC 4122),
for example, uuid1() for UUID version 1, uuid3() for UUID version 3, and so on.
Note that UUID version 2 is deliberately omitted as it is outside the scope of the RFC.
如果你只需要一個唯一的 ID，你應該呼叫 uuid1() 或 uuid4()。需要注意的是，uuid1() 可能會危害隱私，因為它會建立一個包含了電腦網路位址的 UUID。而 uuid4() 則會建立一個隨機的 UUID。
根據底層平台的支援情況，uuid1() 可能會也可能不會回傳一個「安全的」UUID。安全的 UUID 是使用同步方法生成的，以確保不會有兩個行程獲取到相同的 UUID。所有 UUID 的實例都有一個 is_safe 屬性，該屬性使用下面這個列舉來傳遞有關 UUID 安全性的任何資訊：
- class uuid.SafeUUID¶
在 3.7 版被加入.
- safe¶
該 UUID 是由平台以多行程安全的 (multiprocessing-safe) 方式生成的。
- unsafe¶
該 UUID 不是以多行程安全的方式生成的。
- unknown¶
該平台不提供 UUID 是否為安全生成的資訊。
- class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)¶
從以下其中一種引數來建立 UUID：由 32 個十六進位的數字組成的字串、以大端順序 (big-endian) 排列的 16 個位元組組成的字串作為 bytes 引數、以小端順序 (little-endian) 排列的 16 個位元組組成的字串作為 bytes_le 引數、由 6 個整數（32 位元的 time_low、16 位元的 time_mid、16 位元的 time_hi_version、8 位元的 clock_seq_hi_variant、8 位元的 clock_seq_low、48 位元的 node）組成的元組 (tuple) 作為 fields 引數，或者是單一的 128 位元整數作為 int 引數。當給定由十六進位的數字組成的字串時，大括號、連字符號和 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)
Exactly one of hex, bytes, bytes_le, fields, or int must be given. The version argument is optional; if given, the resulting UUID will have its variant and version number set according to RFC 9562, overriding bits in the given hex, bytes, bytes_le, fields, or int.
UUID 物件之間的比較是透過比較它們的
UUID.int屬性。與非 UUID 的物件進行比較會引發TypeError。str(uuid)會回傳一個像是12345678-1234-5678-1234-567812345678形式的字串，其中 32 個十六進位的數字代表 UUID。
UUID 實例有以下唯讀的屬性：
- UUID.bytes¶
UUID 以 16 位元組的字串表示（包含 6 個整數欄位，按照大端位元組順序排列）。
- UUID.bytes_le¶
UUID 以 16 位元組的字串表示（其中 time_low、time_mid 和 time_hi_version 按照小端位元組順序排列）。
- UUID.fields¶
UUID 以 6 個整數欄位所組成的元組表示，也可以看作有 6 個個別屬性和 2 個衍生屬性：
欄位 |
意義 |
|
The first 32 bits of the UUID. Only relevant to version 1. |
|
The next 16 bits of the UUID. Only relevant to version 1. |
|
The next 16 bits of the UUID. Only relevant to version 1. |
|
The next 8 bits of the UUID. Only relevant to versions 1 and 6. |
|
The next 8 bits of the UUID. Only relevant to versions 1 and 6. |
|
The last 48 bits of the UUID. Only relevant to version 1. |
|
The 60-bit timestamp for version 1 and 6, or the 48-bit timestamp for version 7. |
|
The 14-bit sequence number. Only relevant to versions 1 and 6. |
- UUID.hex¶
UUID 以 32 個小寫十六進位字元組成的字串表示。
- UUID.int¶
UUID 以 128 位元的整數表示。
- UUID.variant¶
UUID 的變體，決定 UUID 內部的佈局 (layout)，是
RESERVED_NCS、RFC_4122、RESERVED_MICROSOFT或RESERVED_FUTURE其中一個常數。
- UUID.version¶
The UUID version number (1 through 8, meaningful only when the variant is
RFC_4122).在 3.14 版的變更: Added UUID versions 6, 7 and 8.
uuid 模組定義了以下函式：
- uuid.getnode()¶
取得 48 位元正整數形式的硬體位址。第一次執行時，有可能會啟動一個獨立的程式，這也許會相當耗時。如果所有獲取硬體位址的嘗試都失敗，我們會根據 RFC 4122 中的建議，使用一個 48 位元的隨機數，其中群播位元 (multicast bit)（第一個八位元組的最低有效位）設置為 1。「硬體位址」指的是網路介面 (network interface) 的 MAC 位址。在具有多個網路介面的機器上，將優先選擇通用管理 (universally administered) 的 MAC 位址（即第一個八位元組的第二個最低有效位是 未設置的），而不是本地管理 (locally administered) 的 MAC 位址，除此之外不保證任何選擇的順序。
在 3.7 版的變更: 通用管理的 MAC 位址優於本地管理的 MAC 位址，因為前者保證是全球唯一的，而後者不是。
- uuid.uuid1(node=None, clock_seq=None)¶
從主機 ID、序列號和當前時間生成 UUID。如果未給定 node，將使用
getnode()獲取硬體位址。如果給定 clock_seq，會將其用作序列號；否則將使用一個隨機 14 位元的序列號。
- uuid.uuid3(namespace, name)¶
基於命名空間識別碼 (namespace identifier)（一個 UUID）和名稱（一個
bytes物件或使用 UTF-8 編碼的字串）的 MD5 hash 來生成 UUID。
- uuid.uuid4()¶
生成一個隨機的 UUID。
- uuid.uuid5(namespace, name)¶
基於命名空間識別碼（一個 UUID）和名稱（一個
bytes物件或使用 UTF-8 編碼的字串）的 SHA-1 hash 來生成 UUID。
- uuid.uuid6(node=None, clock_seq=None)¶
Generate a UUID from a sequence number and the current time according to RFC 9562. This is an alternative to
uuid1()to improve database locality.When node is not specified,
getnode()is used to obtain the hardware address as a 48-bit positive integer. When a sequence number clock_seq is not specified, a pseudo-random 14-bit positive integer is generated.If node or clock_seq exceed their expected bit count, only their least significant bits are kept.
在 3.14 版被加入.
- uuid.uuid7()¶
Generate a time-based UUID according to RFC 9562, §5.7.
For portability across platforms lacking sub-millisecond precision, UUIDs produced by this function embed a 48-bit timestamp and use a 42-bit counter to guarantee monotonicity within a millisecond.
在 3.14 版被加入.
- uuid.uuid8(a=None, b=None, c=None)¶
Generate a pseudo-random UUID according to RFC 9562, §5.8.
When specified, the parameters a, b and c are expected to be positive integers of 48, 12 and 62 bits respectively. If they exceed their expected bit count, only their least significant bits are kept; non-specified arguments are substituted for a pseudo-random integer of appropriate size.
在 3.14 版被加入.
uuid 模組為 uuid3() 或 uuid5() 定義了以下的命名空間識別碼。
- uuid.NAMESPACE_DNS¶
當指定這個命名空間時，name 字串是一個完整網域名稱 (fully qualified domain 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.RFC_4122¶
Specifies the UUID layout given in RFC 4122. This constant is kept for backward compatibility even though RFC 4122 has been superseded by RFC 9562.
- uuid.RESERVED_MICROSOFT¶
保留供 Microsoft 相容性使用。
- uuid.RESERVED_FUTURE¶
保留供未來定義使用。
The uuid module defines the special Nil and Max UUID values:
- uuid.NIL¶
A special form of UUID that is specified to have all 128 bits set to zero according to RFC 9562, §5.9.
在 3.14 版被加入.
- uuid.MAX¶
A special form of UUID that is specified to have all 128 bits set to one according to RFC 9562, §5.10.
在 3.14 版被加入.
也參考
- RFC 9562 - A Universally Unique IDentifier (UUID) URN Namespace
這個規範定義了 UUID 的統一資源名稱 (Uniform Resource Name) 命名空間、UUID 的內部格式和生成 UUID 的方法。
命令列的用法¶
在 3.12 版被加入.
uuid 模組可以在命令列下作為腳本來執行。
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]
可以接受以下選項：
- -h, --help¶
顯示幫助訊息並退出。
- -u <uuid>¶
- --uuid <uuid>¶
指定要用來生成 UUID 的函式名稱。預設使用
uuid4()。在 3.14 版的變更: Allow generating UUID versions 6, 7 and 8.
範例¶
以下是一些 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')
命令列的範例¶
Here are some examples of typical usage of the uuid command-line interface:
# 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