uuid — 根據 RFC 4122 的 UUID 物件

原始碼: Lib/uuid.py

---

此模組提供了不可變的 UUID 物件（UUID 類）和函式 uuid1()、uuid3()、uuid4()、uuid5()，用於生成 RFC 4122 中指定的版本 1、3、4 和 5 的 UUID。

如果你只需要一個唯一的 ID，你可能應該呼叫 uuid1() 或 uuid4()。請注意，uuid1() 可能會洩露隱私，因為它會建立一個包含計算機網路地址的 UUID。uuid4() 會建立一個隨機的 UUID。

根據底層平臺的支援，uuid1() 可能會也可能不會返回“安全”的 UUID。安全的 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 個十六進位制數字的字串、作為 bytes 引數的大端順序的 16 位元組字串、作為 bytes_le 引數的小端順序的 16 位元組字串、六個整數（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 4122 設定其變體和版本號，從而覆蓋給定的 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.time_low	UUID 的前 32 位。
UUID.time_mid	UUID 的接下來的 16 位。
UUID.time_hi_version	UUID 的接下來的 16 位。
UUID.clock_seq_hi_variant	UUID 的接下來的 8 位。
UUID.clock_seq_low	UUID 的接下來的 8 位。
UUID.node	UUID 的最後 48 位。
UUID.time	60 位的時間戳。
UUID.clock_seq	14 位的序列號。

UUID.hex

UUID 作為 32 個字元的小寫十六進位制字串。

UUID.int

UUID 作為 128 位整數。

UUID.urn

UUID 作為 RFC 4122 中指定的 URN。

UUID.variant

UUID 變體，它決定了 UUID 的內部佈局。這將是常量 RESERVED_NCS、RFC_4122、RESERVED_MICROSOFT 或 RESERVED_FUTURE 之一。

UUID.version

UUID 版本號（1 到 5，僅當變體為 RFC_4122 時才有意義）。

UUID.is_safe

一個 SafeUUID 的列舉，指示平臺是否以多程序安全的方式生成 UUID。

在 3.7 版本中新增。

uuid 模組定義了以下函式

uuid.getnode()

獲取硬體地址作為 48 位正整數。第一次執行時，它可能會啟動一個單獨的程式，這可能會很慢。如果所有獲取硬體地址的嘗試都失敗，我們將選擇一個隨機的 48 位數字，並將多播位（第一個八位位元組的最低有效位）設定為 1，這是 RFC 4122 中推薦的。“硬體地址”是指網路介面的 MAC 地址。在具有多個網路介面的機器上，全域性管理的 MAC 地址（即第一個八位位元組的次低有效位未設定）將優先於本地管理的 MAC 地址，但沒有其他排序保證。

在 3.7 版本中變更: 全域性管理的 MAC 地址優先於本地管理的 MAC 地址，因為前者保證是全域性唯一的，而後者則不是。

uuid.uuid1(node=None, clock_seq=None)

從主機 ID、序列號和當前時間生成 UUID。 如果沒有給出 node，則使用 getnode() 獲取硬體地址。如果給出了 clock_seq，則將其用作序列號；否則，將選擇一個隨機的 14 位序列號。

uuid.uuid3(namespace, name)

基於名稱空間識別符號（是一個 UUID）和一個名稱（是一個 bytes 物件或一個將使用 UTF-8 編碼的字串）的 MD5 雜湊生成 UUID。

uuid.uuid4()

生成一個隨機 UUID。

uuid.uuid5(namespace, name)

基於名稱空間識別符號（是一個 UUID）和一個名稱（是一個 bytes 物件或一個將使用 UTF-8 編碼的字串）的 SHA-1 雜湊生成 UUID。

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.RFC_4122

指定 RFC 4122 中給出的 UUID 佈局。

uuid.RESERVED_MICROSOFT

保留用於 Microsoft 相容性。

uuid.RESERVED_FUTURE

保留用於未來定義。

另請參閱

RFC 4122 - 通用唯一識別符號 (UUID) URN 名稱空間

本規範定義了 UUID 的統一資源名稱名稱空間、UUID 的內部格式以及生成 UUID 的方法。

命令列用法

在 3.12 版本中新增。

uuid 模組可以從命令列作為指令碼執行。

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME]

接受以下選項

-h, --help

顯示幫助訊息並退出。

-u <uuid>

--uuid <uuid>

指定用於生成 uuid 的函式名稱。預設情況下，使用 uuid4()。

-n <namespace>

--namespace <namespace>

名稱空間是一個 UUID，或者是一個 @ns，其中 ns 是一個眾所周知的、由名稱空間名稱定址的預定義 UUID。 例如 @dns, @url, @oid, 和 @x500。僅當使用 uuid3() / uuid5() 函式時才需要。

-N <name>

--name <name>

用作生成 uuid 一部分的名稱。僅當使用 uuid3() / uuid5() 函式時才需要。

示例

以下是 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')

命令列示例

以下是 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