`uuid` --- đối tượng UUID theo RFC 9562¶

Source code: Lib/uuid.py

Mô-đun này cung cấp các đối tượng UUID bất biến (lớp UUID) và functions để tạo UUID tương ứng với một phiên bản UUID cụ thể như được chỉ định trong RFC 9562 (thay thế RFC 4122), ví dụ: uuid1() cho UUID phiên bản 1, uuid3() cho UUID phiên bản 3, v.v. Lưu ý rằng UUID phiên bản 2 bị cố tình bỏ qua vì nó nằm ngoài phạm vi của RFC.

Nếu tất cả những gì bạn muốn là một ID duy nhất, có lẽ bạn nên gọi uuid1() hoặc uuid4(). Lưu ý rằng uuid1() có thể xâm phạm quyền riêng tư vì nó tạo ra UUID chứa địa chỉ mạng của máy tính. uuid4() tạo một UUID ngẫu nhiên.

Tùy thuộc vào sự hỗ trợ từ nền tảng cơ bản, uuid1() có thể trả về hoặc không trả về UUID "an toàn". Một UUID an toàn là một UUID được tạo bằng các phương pháp đồng bộ hóa để đảm bảo không có hai quy trình nào có thể có được UUID giống nhau. Tất cả các phiên bản của UUID đều có thuộc tính is_safe chuyển tiếp bất kỳ thông tin nào về sự an toàn của UUID, sử dụng bảng liệt kê này:

class uuid.SafeUUID¶

Added in version 3.7.

safe¶: Zz000zz được nền tảng tạo ra theo cách an toàn đa xử lý.

unsafe¶: Zz000zz không được tạo theo cách an toàn đa xử lý.

unknown¶: Nền tảng này không cung cấp thông tin về việc UUID có được tạo an toàn hay không.

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)¶

Tạo một UUID từ một chuỗi gồm 32 chữ số thập lục phân, một chuỗi 16 byte theo thứ tự lớn làm đối số bytes, một chuỗi 16 byte theo thứ tự cuối nhỏ làm đối số bytes_le, một bộ gồm sáu số nguyên (time_low 32 bit, time_mid 16 bit, time_hi_version 16 bit, clock_seq_hi_variant 8 bit, clock_seq_low 8 bit, node 48 bit) làm đối số fields hoặc một số nguyên 128 bit duy nhất làm đối số int. Khi một chuỗi chữ số hex được cung cấp, dấu ngoặc nhọn, dấu gạch nối và tiền tố URN đều là tùy chọn. Ví dụ: tất cả các biểu thức này đều mang lại cùng một UUID:

UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(byte=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)

Phải cung cấp chính xác một trong các hex, bytes, bytes_le, fields hoặc int. Đối số version là tùy chọn; nếu được cung cấp, UUID kết quả sẽ có biến thể và số phiên bản được đặt theo RFC 9562, ghi đè các bit trong hex, bytes, bytes_le, fields hoặc int nhất định.

So sánh các đối tượng UUID được thực hiện bằng cách so sánh các thuộc tính UUID.int của chúng. So sánh với một đối tượng không phải là UUID sẽ tạo ra TypeError.

str(uuid) trả về một chuỗi ở dạng 12345678-1234-5678-1234-567812345678 trong đó 32 chữ số thập lục phân đại diện cho UUID.

Các phiên bản UUID có các thuộc tính chỉ đọc sau:

UUID.bytes¶: Zz000zz dưới dạng chuỗi 16 byte (chứa sáu trường số nguyên theo thứ tự byte cuối lớn).

UUID.bytes_le¶: UUID dưới dạng chuỗi 16 byte (với time_low, time_mid và time_hi_version theo thứ tự byte cuối nhỏ).

UUID.fields¶: Một bộ gồm sáu trường số nguyên của UUID, cũng có sẵn dưới dạng sáu thuộc tính riêng lẻ và hai thuộc tính dẫn xuất:

trường	Ý nghĩa
UUID.time_low¶	32 bit đầu tiên của UUID. Chỉ liên quan đến phiên bản 1.
UUID.time_mid¶	16 bit tiếp theo của UUID. Chỉ liên quan đến phiên bản 1.
UUID.time_hi_version¶	16 bit tiếp theo của UUID. Chỉ liên quan đến phiên bản 1.
UUID.clock_seq_hi_variant¶	8 bit tiếp theo của UUID. Chỉ liên quan đến phiên bản 1 và 6.
UUID.clock_seq_low¶	8 bit tiếp theo của UUID. Chỉ liên quan đến phiên bản 1 và 6.
UUID.node¶	48 bit cuối cùng của UUID. Chỉ liên quan đến phiên bản 1.
UUID.time¶	Dấu thời gian 60 bit dưới dạng khoảng thời gian 100 nano giây kể từ kỷ nguyên Gregorian (1582-10-15 00:00:00) cho phiên bản 1 và 6 hoặc dấu thời gian 48 bit tính bằng mili giây kể từ kỷ nguyên Unix (1970-01-01 00:00:00) cho phiên bản 7.
UUID.clock_seq¶	Số thứ tự 14 bit. Chỉ liên quan đến phiên bản 1 và 6.

UUID.hex¶: Zz000zz dưới dạng chuỗi thập lục phân viết thường gồm 32 ký tự.

UUID.int¶: Zz000zz là số nguyên 128 bit.

UUID.urn¶: UUID là URN như được chỉ định trong RFC 9562.

UUID.variant¶: Biến thể UUID xác định bố cục bên trong của UUID. Đây sẽ là một trong các hằng số RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT hoặc RESERVED_FUTURE.

UUID.version¶: Số phiên bản UUID (1 đến 8, chỉ có ý nghĩa khi biến thể là RFC_4122).

Thay đổi trong phiên bản 3.14: Đã thêm phiên bản UUID 6, 7 và 8.

UUID.is_safe¶: Một bảng liệt kê SafeUUID cho biết liệu nền tảng có tạo ra UUID theo cách an toàn đa xử lý hay không.

Added in version 3.7.

Mô-đun uuid xác định các chức năng sau:

uuid.getnode()¶: Lấy địa chỉ phần cứng dưới dạng số nguyên dương 48 bit. Trong lần chạy đầu tiên, nó có thể khởi chạy một chương trình riêng biệt và có thể khá chậm. Nếu mọi nỗ lực lấy địa chỉ phần cứng đều không thành công, chúng tôi sẽ chọn một số 48 bit ngẫu nhiên có bit multicast (bit ít quan trọng nhất của octet đầu tiên) được đặt thành 1 như được khuyến nghị trong RFC 4122. "Địa chỉ phần cứng" nghĩa là địa chỉ MAC của giao diện mạng. Trên máy có nhiều giao diện mạng, các địa chỉ MAC được quản lý phổ biến (tức là bit có ý nghĩa nhỏ thứ hai của octet đầu tiên là unset) sẽ được ưu tiên hơn các địa chỉ MAC được quản lý cục bộ nhưng không có đảm bảo thứ tự nào khác.

Thay đổi trong phiên bản 3.7: Các địa chỉ MAC được quản lý toàn cầu được ưu tiên hơn các địa chỉ MAC được quản lý cục bộ, vì các địa chỉ trước đây được đảm bảo là duy nhất trên toàn cầu, trong khi các địa chỉ sau thì không.

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

Tạo UUID từ ID máy chủ, số thứ tự và thời gian hiện tại theo RFC 9562, §5.1.

Khi node không được chỉ định, getnode() được sử dụng để lấy địa chỉ phần cứng dưới dạng số nguyên dương 48 bit. Khi số thứ tự clock_seq không được chỉ định, số nguyên dương 14 bit giả ngẫu nhiên sẽ được tạo.

Nếu node hoặc clock_seq vượt quá số bit dự kiến thì chỉ những bit có ý nghĩa nhỏ nhất được giữ lại.

uuid.uuid3(namespace, name)¶: Tạo UUID dựa trên hàm băm MD5 của mã định danh không gian tên (là UUID) và tên (là đối tượng bytes hoặc chuỗi sẽ được mã hóa bằng UTF-8) theo RFC 9562, §5.3.

uuid.uuid4()¶: Tạo một UUID ngẫu nhiên theo phương pháp bảo mật bằng mật mã theo RFC 9562, §5.4.

uuid.uuid5(namespace, name)¶: Tạo UUID dựa trên hàm băm SHA-1 của mã định danh không gian tên (là UUID) và tên (là đối tượng bytes hoặc chuỗi sẽ được mã hóa bằng UTF-8) theo RFC 9562, §5.5.

uuid.uuid6(node=None, clock_seq=None)¶

Tạo UUID từ số thứ tự và thời gian hiện tại theo RFC 9562, §5.6.

Đây là một giải pháp thay thế cho uuid1() để cải thiện vị trí cơ sở dữ liệu.

Khi node không được chỉ định, getnode() được sử dụng để lấy địa chỉ phần cứng dưới dạng số nguyên dương 48 bit. Khi số thứ tự clock_seq không được chỉ định, số nguyên dương 14 bit giả ngẫu nhiên sẽ được tạo.

Nếu node hoặc clock_seq vượt quá số bit dự kiến thì chỉ những bit có ý nghĩa nhỏ nhất được giữ lại.

Added in version 3.14.

uuid.uuid7()¶

Tạo UUID dựa trên thời gian theo RFC 9562, §5.7.

Để có khả năng di động trên các nền tảng thiếu độ chính xác dưới một phần nghìn giây, UUID do chức năng này tạo ra sẽ nhúng dấu thời gian 48 bit và sử dụng bộ đếm 42 bit để đảm bảo tính đơn điệu trong vòng một phần nghìn giây.

Added in version 3.14.

uuid.uuid8(a=None, b=None, c=None)¶

Tạo UUID giả ngẫu nhiên theo RFC 9562, §5.8.

Khi được chỉ định, các tham số a, b và c dự kiến sẽ là số nguyên dương lần lượt là 48, 12 và 62 bit. Nếu chúng vượt quá số bit dự kiến, chỉ những bit có ý nghĩa nhỏ nhất của chúng được giữ lại; các đối số không được chỉ định được thay thế bằng số nguyên giả ngẫu nhiên có kích thước phù hợp.

Theo mặc định, a, b và c không được tạo bởi trình tạo số giả ngẫu nhiên được bảo mật bằng mật mã (CSPRNG). Sử dụng uuid4() khi cần sử dụng UUID trong bối cảnh nhạy cảm về bảo mật.

Added in version 3.14.

Mô-đun uuid xác định các mã định danh vùng tên sau để sử dụng với uuid3() hoặc uuid5().

uuid.NAMESPACE_DNS¶: Khi không gian tên này được chỉ định, chuỗi name là tên miền đủ điều kiện.

uuid.NAMESPACE_URL¶: Khi không gian tên này được chỉ định, chuỗi name là URL.

uuid.NAMESPACE_OID¶: Khi không gian tên này được chỉ định, chuỗi name là ISO OID.

uuid.NAMESPACE_X500¶: Khi không gian tên này được chỉ định, chuỗi name là X.500 DN ở DER hoặc định dạng đầu ra văn bản.

Mô-đun uuid xác định các hằng số sau cho các giá trị có thể có của thuộc tính variant:

uuid.RESERVED_NCS¶: Dành riêng cho khả năng tương thích NCS.

uuid.RFC_4122¶: Chỉ định bố cục UUID được cung cấp trong RFC 4122. Hằng số này được giữ để tương thích ngược mặc dù RFC 4122 đã được thay thế bởi RFC 9562.

uuid.RESERVED_MICROSOFT¶: Dành riêng cho khả năng tương thích của Microsoft.

uuid.RESERVED_FUTURE¶: Dành riêng cho định nghĩa trong tương lai.

Mô-đun uuid xác định các giá trị Nil và Max UUID đặc biệt:

uuid.NIL¶: Một dạng đặc biệt của UUID được chỉ định để có tất cả 128 bit được đặt thành 0 theo RFC 9562, §5.9.

Added in version 3.14.

uuid.MAX¶: Một dạng đặc biệt của UUID được chỉ định để có tất cả 128 bit được đặt thành một theo RFC 9562, §5.10.

Added in version 3.14.

Xem thêm

RFC 9562 - Không gian tên định danh duy nhất toàn cầu (UUID) URN: Thông số kỹ thuật này xác định không gian tên Tên tài nguyên thống nhất cho UUID, định dạng bên trong của UUID và phương pháp tạo UUID.

Sử dụng dòng lệnh¶

Added in version 3.12.

Mô-đun uuid có thể được thực thi dưới dạng tập lệnh từ dòng lệnh.

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

Các tùy chọn sau được chấp nhận:

-h, --help¶: Hiển thị thông báo trợ giúp và thoát.

-u <uuid>¶
--uuid <uuid>¶: Chỉ định tên hàm sẽ sử dụng để tạo uuid. Theo mặc định, uuid4() được sử dụng.

Thay đổi trong phiên bản 3.14: Cho phép tạo UUID phiên bản 6, 7 và 8.

-n <namespace>¶
--namespace <namespace>¶: Không gian tên là UUID hoặc @ns trong đó ns là UUID được xác định trước phổ biến và được xử lý theo tên không gian tên. Chẳng hạn như @dns, @url, @oid và @x500. Chỉ bắt buộc đối với các chức năng uuid3() / uuid5().

-N <name>¶
--name <name>¶: Tên được sử dụng như một phần của việc tạo uuid. Chỉ bắt buộc đối với các chức năng uuid3() / uuid5().

-C <num>¶
--count <num>¶: Tạo UUID mới num.

Added in version 3.14.

Ví dụ¶

Dưới đây là một số ví dụ về cách sử dụng điển hình của mô-đun 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')

Ví dụ dòng lệnh¶

Dưới đây là một số ví dụ về cách sử dụng điển hình của giao diện dòng lệnh uuid:

# generate một UUID ngẫu nhiên - theo mặc định uuid4() được sử dụng
$ trăn -m uuid

# generate và UUID sử dụng uuid1()
$ trăn -m uuid -u uuid1

# generate và UUID sử dụng uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

# generate 42 UUID ngẫu nhiên
$ trăn -m uuid -C 42

`uuid` --- đối tượng UUID theo RFC 9562¶

Sử dụng dòng lệnh¶

Ví dụ¶

Ví dụ dòng lệnh¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

uuid --- đối tượng UUID theo RFC 9562¶

Sử dụng dòng lệnh¶

Ví dụ¶

Ví dụ dòng lệnh¶

`uuid` --- đối tượng UUID theo RFC 9562¶