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