`enum` --- Hỗ trợ liệt kê¶

Added in version 3.4.

Source code: Lib/enum.py

Một phép liệt kê:

là một tập hợp các tên tượng trưng (thành viên) được liên kết với các giá trị duy nhất
có thể được lặp đi lặp lại để trả về các thành viên chính tắc (tức là không phải bí danh) theo thứ tự định nghĩa
sử dụng cú pháp call để trả về các thành viên theo giá trị
sử dụng cú pháp index để trả về thành viên theo tên

Các bảng liệt kê được tạo bằng cách sử dụng cú pháp class hoặc bằng cách sử dụng cú pháp gọi hàm

>>> từ nhập enum Enum

>>> cú pháp # class
>>> Màu lớp (Enum):
... RED = 1
... GREEN = 2
... BLUE = 3

>>> cú pháp # functional
>>> Màu = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])

Mặc dù chúng ta có thể sử dụng cú pháp class để tạo Enum, nhưng Enum không phải là các lớp Python bình thường. Xem How are Enums different? để biết thêm chi tiết.

Ghi chú

Danh pháp

Lớp Color là enumeration (hoặc enum)
Các thuộc tính Color.RED, Color.GREEN, v.v., là enumeration members (hoặc members) và là các hằng số chức năng.
Các thành viên enum có names và values (tên của Color.RED là RED, giá trị của Color.BLUE là 3, v.v.)

Nội dung mô-đun¶

EnumType

Zz000zz cho Enum và các lớp con của nó.

Enum

Lớp cơ sở để tạo các hằng số liệt kê.

IntEnum

Lớp cơ sở để tạo các hằng số liệt kê cũng là lớp con của int. (Notes)

StrEnum

Lớp cơ sở để tạo các hằng số liệt kê cũng là lớp con của str. (Notes)

Flag

Lớp cơ sở để tạo các hằng số liệt kê có thể được kết hợp bằng cách sử dụng các phép toán theo bit mà không làm mất tư cách thành viên Flag của chúng.

IntFlag

Lớp cơ sở để tạo các hằng số liệt kê có thể được kết hợp bằng cách sử dụng các toán tử bitwise mà không làm mất tư cách thành viên IntFlag của chúng. Các thành viên IntFlag cũng là lớp con của int. (Notes)

ReprEnum

Được sử dụng bởi IntEnum, StrEnum và IntFlag để giữ str() thuộc loại hỗn hợp.

EnumCheck

Một bảng liệt kê có các giá trị CONTINUOUS, NAMED_FLAGS và UNIQUE để sử dụng với verify() nhằm đảm bảo các ràng buộc khác nhau được đáp ứng bởi một bảng liệt kê nhất định.

FlagBoundary

Một bảng liệt kê có các giá trị STRICT, CONFORM, EJECT và KEEP cho phép kiểm soát chi tiết hơn cách xử lý các giá trị không hợp lệ trong một bảng liệt kê.

EnumDict

Một lớp con của dict để sử dụng khi phân lớp EnumType.

auto

Các phiên bản được thay thế bằng một giá trị phù hợp cho các thành viên Enum. StrEnum mặc định là phiên bản viết thường của tên thành viên, trong khi các Enum khác mặc định là 1 và tăng dần từ đó.

property()

Cho phép thành viên Enum có thuộc tính mà không xung đột với tên thành viên. Thuộc tính value và name được triển khai theo cách này.

unique()

Trình trang trí lớp Enum đảm bảo chỉ có một tên được liên kết với bất kỳ một giá trị nào.

verify()

Trình trang trí lớp Enum kiểm tra các ràng buộc do người dùng lựa chọn trên một bảng liệt kê.

member()

Hãy biến obj thành thành viên. Có thể được sử dụng như một vật trang trí.

nonmember()

Đừng biến obj thành thành viên. Có thể được sử dụng như một vật trang trí.

global_enum()

Sửa đổi str() và repr() của một enum để hiển thị các thành viên của nó thuộc về mô-đun thay vì lớp của nó và xuất các thành viên enum sang không gian tên chung.

show_flag_values()

Trả về danh sách tất cả các số nguyên lũy thừa hai có trong một cờ.

enum.bin()

Giống như bin() tích hợp, ngoại trừ các giá trị âm được biểu thị dưới dạng phần bù hai và bit đầu luôn biểu thị dấu (0 ngụ ý dương, 1 ngụ ý âm).

Added in version 3.6: Flag, IntFlag, auto

Added in version 3.11: StrEnum, EnumCheck, ReprEnum, FlagBoundary, property, member, nonmember, global_enum, show_flag_values

Added in version 3.13: EnumDict

Các kiểu dữ liệu¶

class enum.EnumType¶

EnumType là metaclass cho bảng liệt kê enum. Có thể phân lớp EnumType -- xem Subclassing EnumType để biết chi tiết.

EnumType chịu trách nhiệm thiết lập các phương thức __repr__(), __str__(), __format__() và __reduce__() chính xác trên enum cuối cùng, cũng như tạo các thành viên enum, xử lý đúng cách các bản sao, cung cấp phép lặp trên lớp enum, v.v.

Added in version 3.11: Trước 3.11 EnumType được gọi là EnumMeta, tên này vẫn có sẵn dưới dạng bí danh.

__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Phương pháp này được gọi theo hai cách khác nhau:

để tra cứu một thành viên hiện có:

cls:

Lớp enum đang được gọi.

giá trị:

Giá trị cần tra cứu.
để sử dụng enum cls để tạo một enum mới (chỉ khi enum hiện tại không có thành viên nào):

cls:

Lớp enum đang được gọi.

giá trị:

Tên của Enum mới cần tạo.

tên:

Tên/giá trị của các thành viên cho Enum mới.

mô-đun:

Tên của mô-đun mà Enum mới được tạo trong đó.

tên chất lượng:

Vị trí thực tế trong mô-đun nơi có thể tìm thấy Enum này.

loại:

Một loại kết hợp cho Enum mới.

bắt đầu:

Giá trị số nguyên đầu tiên cho Enum (được sử dụng bởi auto).

ranh giới:

Cách xử lý các giá trị ngoài phạm vi từ các thao tác bit (chỉ Flag).

__contains__(cls, member)¶

Trả về True nếu thành viên thuộc cls:

>>> some_var = Color.RED
>>> some_var có màu
đúng
>>> Color.RED.value về Màu sắc
đúng

Thay đổi trong phiên bản 3.12: Trước Python 3.12, TypeError sẽ được nâng lên nếu sử dụng một thành viên không phải là thành viên Enum trong quá trình kiểm tra ngăn chặn.

__dir__(cls)¶

Trả về ['__class__', '__doc__', '__members__', '__module__'] và tên của các thành viên trong cls:

>>> thư mục(Màu)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']

__getitem__(cls, name)¶

Trả về thành viên Enum trong cls khớp với name hoặc tăng KeyError:

>>> Màu sắc['BLUE']
<Color.BLUE: 3>

__iter__(cls)¶

Trả về từng thành viên trong cls theo thứ tự định nghĩa:

>>> danh sách (Màu)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

__len__(cls)¶

Trả về số lượng thành viên trong cls:

>>> len(Màu)
3

__members__¶: Trả về ánh xạ của mọi tên enum cho thành viên của nó, bao gồm cả bí danh

__reversed__(cls)¶

Trả về từng thành viên trong cls theo thứ tự định nghĩa ngược:

>>> danh sách (đảo ngược (Màu))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

class enum.Enum¶

Enum là lớp cơ sở cho tất cả các bảng liệt kê enum.

name¶

Tên dùng để xác định thành viên Enum:

>>> Color.BLUE.name
'BLUE'

value¶

Giá trị được trao cho thành viên Enum:

>>> Color.RED.value
1

Giá trị của thành viên, có thể được đặt bằng __new__().

Ghi chú

Giá trị thành viên Enum

Giá trị thành viên có thể là bất cứ thứ gì: int, str, v.v. Nếu giá trị chính xác không quan trọng, bạn có thể sử dụng phiên bản auto và một giá trị thích hợp sẽ được chọn cho bạn. Xem auto để biết chi tiết.

Mặc dù có thể sử dụng các giá trị có thể thay đổi/không thể băm, chẳng hạn như dict, list hoặc dataclass có thể thay đổi, nhưng chúng sẽ có tác động hiệu suất bậc hai trong quá trình tạo so với tổng số giá trị có thể thay đổi/không thể băm trong enum.

_name_¶: Tên của thành viên.

_value_¶: Giá trị của thành viên, có thể được đặt bằng __new__().

_order_¶

Không còn được sử dụng, được giữ lại để tương thích ngược. (thuộc tính lớp, bị xóa trong quá trình tạo lớp).

Thuộc tính _order_ có thể được cung cấp để giúp đồng bộ hóa mã Python 2/Python 3. Nó sẽ được kiểm tra theo thứ tự thực tế của bảng liệt kê và phát sinh lỗi nếu cả hai không khớp

>>> Màu lớp (Enum):
... _order_ = 'RED GREEN BLUE'
... RED = 1
... BLUE = 3
... GREEN = 2
...
Traceback (cuộc gọi gần đây nhất):
...
TypeError: thứ tự thành viên không khớp _order_:
   ['RED', 'BLUE', 'GREEN']
   ['RED', 'GREEN', 'BLUE']

Ghi chú

Trong mã Python 2, thuộc tính _order_ là cần thiết vì thứ tự định nghĩa bị mất trước khi có thể ghi lại.

Added in version 3.6.

_ignore_¶

_ignore_ chỉ được sử dụng trong quá trình tạo và bị xóa khỏi bảng liệt kê sau khi quá trình tạo hoàn tất.

_ignore_ là danh sách những cái tên sẽ không trở thành thành viên và tên của những người này cũng sẽ bị xóa khỏi bảng liệt kê đã hoàn thành. Xem TimePeriod để biết ví dụ.

Added in version 3.7.

__dir__(self)¶

Trả về ['__class__', '__doc__', '__module__', 'name', 'value'] và mọi phương thức công khai được xác định trên self.__class__:

>>> từ nhập enum Enum
>>> nhập ngày giờ dưới dạng dt
>>> lớp Ngày trong tuần(Enum):
... MONDAY = 1
... TUESDAY = 2
... WEDNESDAY = 3
... THURSDAY = 4
... FRIDAY = 5
... SATURDAY = 6
... SUNDAY = 7
... @classmethod
... def hôm nay(cls):
... print(f'hôm nay là {cls(dt.date.today().isoweekday()).name}')
...
>>> thư mục(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'hôm nay', 'giá trị']

_generate_next_value_(name, start, count, last_values)¶

tên:

Tên của thành viên đang được xác định (ví dụ: 'RED').

bắt đầu:

Giá trị bắt đầu cho Enum; mặc định là 1.

đếm:

Số lượng thành viên hiện được xác định, không bao gồm thành viên này.

giá trị cuối cùng:

Danh sách các giá trị trước đó

Một staticmethod được sử dụng để xác định giá trị tiếp theo được trả về bởi auto.

Ghi chú

Đối với các lớp Enum tiêu chuẩn, giá trị tiếp theo được chọn là giá trị cao nhất được tăng thêm một.

Đối với các lớp Flag, giá trị tiếp theo được chọn sẽ là lũy thừa hai cao nhất tiếp theo.

Phương thức này có thể bị ghi đè, ví dụ:

>>> từ tự động nhập enum, Enum
>>> lớp PowersOfThree(Enum):
... @staticmethod
... def _generate_next_value_(tên, bắt đầu, đếm, giá trị cuối cùng):
... trả về 3 ** (đếm + 1)
... FIRST = tự động()
... SECOND = tự động()
...
>>> PowersOfThree.SECOND.value
9

Added in version 3.6.

Thay đổi trong phiên bản 3.13: Các phiên bản trước sẽ sử dụng giá trị nhìn thấy lần cuối thay vì giá trị cao nhất.

__init__(self, *args, **kwds)¶

Theo mặc định, không làm gì cả. Nếu nhiều giá trị được đưa ra trong phân công thành viên, những giá trị đó sẽ trở thành đối số riêng biệt cho __init__; ví dụ.

>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1, 'Mon'

Weekday.__init__() sẽ được gọi là Weekday.__init__(self, 1, 'Mon')

__init_subclass__(cls, **kwds)¶: Một classmethod được sử dụng để cấu hình thêm các lớp con tiếp theo. Theo mặc định, không làm gì cả.

_missing_(cls, value)¶

Một classmethod để tra cứu các giá trị không tìm thấy trong cls. Theo mặc định, nó không làm gì cả nhưng có thể bị ghi đè để triển khai hành vi tìm kiếm tùy chỉnh:

>>> từ tự động nhập enum, StrEnum
>>> Xây dựng lớp(StrEnum):
... DEBUG = tự động()
... OPTIMIZED = tự động()
... @classmethod
... def _missing_(cls, value):
... value = value.low()
... dành cho thành viên trong cls:
... nếu thành viên.value == giá trị:
... thành viên trở lại
... trở lại Không có
...
>>> Build.DEBUG.value
'gỡ lỗi'
>>> Xây dựng('deBUG')
<Build.DEBUG: 'gỡ lỗi'>

Added in version 3.6.

__new__(cls, *args, **kwds)¶

Theo mặc định, không tồn tại. Nếu được chỉ định, trong định nghĩa lớp enum hoặc trong lớp mixin (chẳng hạn như int), tất cả các giá trị được đưa ra trong nhiệm vụ thành viên sẽ được chuyển; ví dụ.

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     TWENTYSIX = '1a', 16

dẫn đến lệnh gọi int('1a', 16) và giá trị 26 cho thành viên.

Ghi chú

Khi viết một __new__ tùy chỉnh, không sử dụng super().__new__ -- thay vào đó hãy gọi __new__ thích hợp.

__repr__(self)¶

Trả về chuỗi được sử dụng cho lệnh gọi repr(). Theo mặc định, trả về tên Enum, tên thành viên và giá trị nhưng có thể bị ghi đè:

>>> từ tự động nhập enum, Enum
>>> lớp OtherStyle(Enum):
... ALTERNATE = tự động()
... OTHER = tự động()
... SOMETHING_ELSE = tự động()
... def __repr__(self):
... cls_name = self.__class__.__name__
... trả về f'{cls_name}.{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')

__str__(self)¶

Trả về chuỗi được sử dụng cho lệnh gọi str(). Theo mặc định, trả về tên Enum và tên thành viên, nhưng có thể bị ghi đè:

>>> từ tự động nhập enum, Enum
>>> lớp OtherStyle(Enum):
... ALTERNATE = tự động()
... OTHER = tự động()
... SOMETHING_ELSE = tự động()
... def __str__(tự):
... return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')

__format__(self)¶

Trả về chuỗi được sử dụng cho lệnh gọi format() và f-string. Theo mặc định, trả về giá trị trả về __str__(), nhưng có thể bị ghi đè:

>>> từ tự động nhập enum, Enum
>>> lớp OtherStyle(Enum):
... ALTERNATE = tự động()
... OTHER = tự động()
... SOMETHING_ELSE = tự động()
... def __format__(self, spec):
... return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

Ghi chú

Sử dụng auto với Enum sẽ tạo ra các số nguyên có giá trị tăng dần, bắt đầu bằng 1.

Thay đổi trong phiên bản 3.12: Đã thêm Hỗ trợ lớp dữ liệu

_add_alias_()¶

Thêm tên mới làm bí danh cho thành viên hiện có:

>>> Color.RED._add_alias_("ERROR")
>>> Color.ERROR
<Color.RED: 1>

Tăng NameError nếu tên đã được gán cho thành viên khác.

Added in version 3.13.

_add_value_alias_()¶

Thêm một giá trị mới làm bí danh cho thành viên hiện có:

>>> Color.RED._add_value_alias_(42)
>>> Màu sắc(42)
<Color.RED: 1>

Tăng ValueError nếu giá trị đã được liên kết với một thành viên khác.

Xem MultiValueEnum để biết ví dụ.

Added in version 3.13.

class enum.IntEnum¶

IntEnum giống như Enum, nhưng các thành viên của nó cũng là số nguyên và có thể được sử dụng ở bất kỳ đâu có thể sử dụng số nguyên. Nếu bất kỳ thao tác số nguyên nào được thực hiện với thành viên IntEnum, giá trị kết quả sẽ mất trạng thái liệt kê.

>>> from enum import IntEnum
>>> class Number(IntEnum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...
>>> Number.THREE
<Number.THREE: 3>
>>> Number.ONE + Number.TWO
3
>>> Number.THREE + 5
8
>>> Number.THREE == 3
True

Ghi chú

Sử dụng auto với IntEnum sẽ tạo ra các số nguyên có giá trị tăng dần, bắt đầu bằng 1.

Thay đổi trong phiên bản 3.11: __str__() hiện là int.__str__() để hỗ trợ tốt hơn cho trường hợp sử dụng replacement of existing constants. __format__() đã là int.__format__() vì lý do tương tự.

class enum.StrEnum¶

StrEnum giống như Enum, nhưng các thành viên của nó cũng là các chuỗi và có thể được sử dụng ở hầu hết các vị trí mà một chuỗi có thể được sử dụng. Kết quả của bất kỳ thao tác chuỗi nào được thực hiện trên hoặc với thành viên StrEnum không phải là một phần của bảng liệt kê.

>>> from enum import StrEnum, auto
>>> class Color(StrEnum):
...     RED = 'r'
...     GREEN = 'g'
...     BLUE = 'b'
...     UNKNOWN = auto()
...
>>> Color.RED
<Color.RED: 'r'>
>>> Color.UNKNOWN
<Color.UNKNOWN: 'unknown'>
>>> str(Color.UNKNOWN)
'unknown'

Ghi chú

Có những vị trí trong stdlib kiểm tra str chính xác thay vì lớp con str (tức là type(unknown) == str thay vì isinstance(unknown, str)) và ở những vị trí đó bạn sẽ cần sử dụng str(MyStrEnum.MY_MEMBER).

Ghi chú

Sử dụng auto với StrEnum sẽ dẫn đến tên thành viên viết thường làm giá trị.

Ghi chú

__str__() là str.__str__() để hỗ trợ tốt hơn cho trường hợp sử dụng replacement of existing constants. __format__() cũng giống str.__format__() vì lý do tương tự.

Added in version 3.11.

class enum.Flag¶

Flag giống như Enum, nhưng các thành viên của nó hỗ trợ các toán tử bitwise & (AND), | (OR), ^ (XOR) và ~ (INVERT); kết quả của các hoạt động đó là (bí danh của) thành viên của bảng liệt kê.

__contains__(self, value)¶

Trả về True nếu giá trị nằm trong self:

>>> từ cờ nhập enum, tự động
>>> Màu lớp (Cờ):
... RED = tự động()
... GREEN = tự động()
... BLUE = tự động()
...
>>> tím = Color.RED | Màu.BLUE
>>> trắng = Color.RED | Color.GREEN | Color.BLUE
>>> Color.GREEN màu tím
sai
>>> Color.GREEN màu trắng
đúng
>>> tím trắng
đúng
>>> trắng tím
sai

__iter__(self):

Trả về tất cả các thành viên không có bí danh:

>>> danh sách(Color.RED)
[<Color.RED: 1>]
>>> danh sách (màu tím)
[<Color.RED: 1>, <Color.BLUE: 4>]

Added in version 3.11.

__len__(self):

Trả về số lượng thành viên trong cờ:

>>> len(Color.GREEN)
1
>>> len(trắng)
3

Added in version 3.11.

__bool__(self):

Trả về True nếu có bất kỳ thành viên nào trong cờ, False nếu không:

>>> bool(Color.GREEN)
đúng
>>> bool(màu trắng)
đúng
>>> đen = Màu(0)
>>> bool(đen)
sai

__or__(self, other)¶

Trả về cờ nhị phân hiện tại hoặc được kết hợp với cờ khác:

>>> Color.RED | Màu.GREEN
<Color.RED|GREEN: 3>

__and__(self, other)¶

Trả về cờ nhị phân hiện tại và được chỉnh sửa bằng cờ khác:

>>> tím và trắng
<Color.RED|BLUE: 5>
>>> tím & Color.GREEN
<Màu sắc: 0>

__xor__(self, other)¶

Trả về cờ nhị phân hiện tại được xor'ed với cờ khác:

>>> tím ^ trắng
<Color.GREEN: 2>
>>> tím ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>

__invert__(self):

Trả về tất cả các cờ trong type(self) không có trong self:

>>> ~trắng
<Màu sắc: 0>
>>> ~màu tím
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>

_numeric_repr_()¶: Hàm dùng để định dạng mọi giá trị số chưa được đặt tên còn lại. Mặc định là giá trị repr; các lựa chọn phổ biến là hex() và oct().

Ghi chú

Sử dụng auto với Flag sẽ tạo ra các số nguyên là lũy thừa của hai, bắt đầu bằng 1.

Thay đổi trong phiên bản 3.11: repr() của các cờ có giá trị bằng 0 đã thay đổi. Bây giờ là:

>>> Color(0)
<Color: 0>

class enum.IntFlag¶

IntFlag giống như Flag, nhưng các thành viên của nó cũng là số nguyên và có thể được sử dụng ở bất kỳ đâu có thể sử dụng số nguyên.

>>> from enum import IntFlag, auto
>>> class Color(IntFlag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> Color.RED & 2
<Color: 0>
>>> Color.RED | 2
<Color.RED|GREEN: 3>

Nếu bất kỳ thao tác số nguyên nào được thực hiện với thành viên IntFlag, kết quả không phải là IntFlag:

>>> Color.RED + 2
3

Nếu thao tác Flag được thực hiện với thành viên IntFlag và:

kết quả là IntFlag hợp lệ: IntFlag được trả về
kết quả không phải là IntFlag hợp lệ: kết quả phụ thuộc vào cài đặt FlagBoundary

repr() của các cờ có giá trị 0 chưa được đặt tên đã thay đổi. Bây giờ là:

>>> Màu sắc(0)
<Màu sắc: 0>

Ghi chú

Sử dụng auto với IntFlag sẽ tạo ra các số nguyên là lũy thừa của hai, bắt đầu bằng 1.

Thay đổi trong phiên bản 3.11: __str__() hiện là int.__str__() để hỗ trợ tốt hơn cho trường hợp sử dụng replacement of existing constants. __format__() đã là int.__format__() vì lý do tương tự.

Đảo ngược IntFlag hiện trả về giá trị dương là sự kết hợp của tất cả các cờ không có trong cờ đã cho, thay vì giá trị âm. Điều này phù hợp với hành vi Flag hiện có.

class enum.ReprEnum¶

ReprEnum sử dụng repr() của Enum, nhưng str() của kiểu dữ liệu hỗn hợp:

int.__str__() cho IntEnum và IntFlag
str.__str__() cho StrEnum

Kế thừa từ ReprEnum để giữ str() / format() của kiểu dữ liệu hỗn hợp thay vì sử dụng str() mặc định Enum.

Added in version 3.11.

class enum.EnumCheck¶

EnumCheck chứa các tùy chọn được trình trang trí verify() sử dụng để đảm bảo các ràng buộc khác nhau; các ràng buộc không thành công sẽ dẫn đến lỗi ValueError.

UNIQUE¶

Đảm bảo rằng mỗi giá trị chỉ có một tên:

>>> from enum import Enum, verify, UNIQUE
>>> @verify(UNIQUE)
... Màu lớp (Enum):
... RED = 1
... GREEN = 2
... BLUE = 3
... CRIMSON = 1
Traceback (cuộc gọi gần đây nhất):
...
ValueError: bí danh được tìm thấy trong <enum 'Color'>: CRIMSON -> RED

CONTINUOUS¶

Đảm bảo rằng không có giá trị bị thiếu giữa thành viên có giá trị thấp nhất và thành viên có giá trị cao nhất:

>>> from enum import Enum, verify, CONTINUOUS
>>> @verify(CONTINUOUS)
... Màu lớp (Enum):
... RED = 1
... GREEN = 2
... BLUE = 5
Traceback (cuộc gọi gần đây nhất):
...
ValueError: enum 'Color' không hợp lệ: thiếu giá trị 3, 4

NAMED_FLAGS¶

Đảm bảo rằng mọi nhóm/mặt nạ cờ chỉ chứa các cờ được đặt tên -- hữu ích khi các giá trị được chỉ định thay vì được tạo bởi auto():

>>> từ cờ nhập enum, xác minh, NAMED_FLAGS
>>> @verify(NAMED_FLAGS)
... Màu lớp (Cờ):
... RED = 1
... GREEN = 2
... BLUE = 4
... WHITE = 15
... NEON = 31
Traceback (cuộc gọi gần đây nhất):
...
ValueError: Cờ 'Màu' không hợp lệ: bí danh WHITE và NEON thiếu các giá trị kết hợp 0x18 [sử dụng enum.show_flag_values(value) để biết chi tiết]

Ghi chú

CONTINUOUS và NAMED_FLAGS được thiết kế để hoạt động với các thành viên có giá trị nguyên.

Added in version 3.11.

class enum.FlagBoundary¶

FlagBoundary kiểm soát cách xử lý các giá trị ngoài phạm vi trong Flag và các lớp con của nó.

STRICT¶

Các giá trị ngoài phạm vi khiến ValueError tăng lên. Đây là mặc định cho Flag:

>>> từ cờ nhập enum, STRICT, auto
>>> lớp StrictFlag(Cờ, ranh giới=STRICT):
... RED = tự động()
... GREEN = tự động()
... BLUE = tự động()
...
>>> Cờ nghiêm ngặt (2**2 + 2**4)
Traceback (cuộc gọi gần đây nhất):
...
ValueError: <flag 'StrictFlag'> giá trị không hợp lệ 20
    cho 0b0 10100
  được phép 0b0 00111

CONFORM¶

Các giá trị ngoài phạm vi đã bị loại bỏ các giá trị không hợp lệ, để lại giá trị Flag hợp lệ:

>>> từ cờ nhập enum, CONFORM, auto
>>> lớp ConformFlag(Cờ, ranh giới=CONFORM):
... RED = tự động()
... GREEN = tự động()
... BLUE = tự động()
...
>>> Cờ phù hợp (2**2 + 2**4)
<ConformFlag.BLUE: 4>

EJECT¶

Các giá trị ngoài phạm vi sẽ mất tư cách thành viên Flag và trở lại int.

>>> from enum import Flag, EJECT, auto
>>> class EjectFlag(Flag, boundary=EJECT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> EjectFlag(2**2 + 2**4)
20

KEEP¶

Các giá trị ngoài phạm vi được giữ lại và tư cách thành viên Flag được giữ lại. Đây là mặc định cho IntFlag:

>>> từ cờ nhập enum, KEEP, auto
>>> lớp KeepFlag(Cờ, ranh giới=KEEP):
... RED = tự động()
... GREEN = tự động()
... BLUE = tự động()
...
>>> KeepFlag(2**2 + 2**4)
<KeepFlag.BLUE|16: 20>

Added in version 3.11.

class enum.EnumDict¶

EnumDict là một lớp con của dict được sử dụng làm không gian tên để xác định các lớp enum (xem Chuẩn bị không gian tên lớp). Nó được cho phép các lớp con của EnumType có hành vi nâng cao như có nhiều giá trị cho mỗi thành viên. Nó phải được gọi với tên của lớp enum đang được tạo, nếu không tên riêng và lớp nội bộ sẽ không được xử lý chính xác.

Lưu ý rằng chỉ có giao diện MutableMapping (__setitem__() và update()) bị ghi đè. Có thể bỏ qua việc kiểm tra bằng các thao tác dict khác như |=.

member_names¶: Danh sách tên các thành viên.

Added in version 3.13.

Tên `dunder` được hỗ trợ¶

__members__ là ánh xạ có thứ tự chỉ đọc của các mục member_name:member. Nó chỉ có sẵn trên lớp.

__new__(), nếu được chỉ định, phải tạo và trả về các thành viên enum; bạn cũng nên đặt _value_ của thành viên một cách thích hợp. Khi tất cả các thành viên được tạo, nó không còn được sử dụng nữa.

Tên `_sunder_` được hỗ trợ¶

_name_ -- tên của thành viên
_value_ -- giá trị của thành viên; có thể được đặt trong __new__
_missing_() -- hàm tra cứu được sử dụng khi không tìm thấy giá trị; có thể bị ghi đè
_ignore_ -- danh sách các tên, dưới dạng list hoặc str, sẽ không được chuyển đổi thành thành viên và sẽ bị xóa khỏi lớp cuối cùng
_order_ -- không còn được sử dụng, được giữ lại để tương thích ngược (thuộc tính lớp, bị xóa trong quá trình tạo lớp)
_generate_next_value_() - được sử dụng để nhận giá trị phù hợp cho thành viên enum; có thể bị ghi đè
_add_alias_() -- thêm tên mới làm bí danh cho thành viên hiện có.
_add_value_alias_() -- thêm giá trị mới làm bí danh cho thành viên hiện có.
Mặc dù tên _sunder_ thường được dành riêng cho sự phát triển hơn nữa của lớp Enum và không thể được sử dụng, một số tên được cho phép rõ ràng:
- _repr_* (ví dụ: _repr_html_), như được sử dụng trong IPython's rich display

Added in version 3.6: _missing_, _order_, _generate_next_value_

Added in version 3.7: _ignore_

Added in version 3.13: _add_alias_, _add_value_alias_, _repr_*

Tiện ích và trang trí¶

class enum.auto¶

auto có thể được sử dụng thay cho một giá trị. Nếu được sử dụng, máy Enum sẽ gọi _generate_next_value_() của Enum để nhận được giá trị phù hợp. Đối với Enum và IntEnum, giá trị thích hợp đó sẽ là giá trị cuối cùng cộng một; đối với Flag và IntFlag, nó sẽ là lũy thừa hai đầu tiên lớn hơn giá trị cao nhất; đối với StrEnum nó sẽ là phiên bản viết thường của tên thành viên. Phải cẩn thận nếu trộn auto() với các giá trị được chỉ định thủ công.

Các phiên bản auto chỉ được giải quyết khi ở cấp cao nhất của một bài tập, tự nó hoặc là một phần của bộ dữ liệu:

FIRST = auto() sẽ hoạt động (auto() được thay thế bằng 1);
SECOND = auto(), -2 sẽ hoạt động (auto được thay thế bằng 2, vì vậy 2, -2 được sử dụng để tạo thành viên enum SECOND;
THREE = [auto(), -3] sẽ not hoạt động ([<auto instance>, -3] được sử dụng để tạo thành viên enum THREE)

Thay đổi trong phiên bản 3.11.1: Trong các phiên bản trước, auto() phải là thứ duy nhất trên dòng nhiệm vụ hoạt động bình thường.

_generate_next_value_ có thể được ghi đè để tùy chỉnh các giá trị được auto sử dụng.

Ghi chú

trong 3.13, _generate_next_value_ mặc định sẽ luôn trả về giá trị thành viên cao nhất tăng thêm 1 và sẽ thất bại nếu bất kỳ thành viên nào thuộc loại không tương thích.

@enum.property¶: Một công cụ trang trí tương tự như property tích hợp sẵn, nhưng đặc biệt dành cho bảng liệt kê. Nó cho phép các thuộc tính thành viên có cùng tên với chính các thành viên đó.

Ghi chú

property và thành viên phải được xác định trong các lớp riêng biệt; ví dụ: các thuộc tính value và name được xác định trong lớp Enum và các lớp con Enum có thể định nghĩa các thành viên có tên value và name.

Added in version 3.11.

@enum.unique¶

Một công cụ trang trí class dành riêng cho bảng liệt kê. Nó tìm kiếm __members__ của một bảng liệt kê, thu thập bất kỳ bí danh nào mà nó tìm thấy; nếu có tìm thấy, ValueError sẽ được nêu ra với các chi tiết:

>>> from enum import Enum, duy nhất
>>> @unique
... Lỗi lớp(Enum):
... ONE = 1
... TWO = 2
... THREE = 3
... FOUR = 3
...
Traceback (cuộc gọi gần đây nhất):
...
ValueError: tìm thấy các giá trị trùng lặp trong <enum 'Mistake'>: FOUR -> THREE

@enum.verify¶: Một công cụ trang trí class dành riêng cho bảng liệt kê. Các thành viên từ EnumCheck được sử dụng để chỉ định những ràng buộc nào cần được kiểm tra trên bảng liệt kê được trang trí.

Added in version 3.11.

@enum.member¶: Một công cụ trang trí để sử dụng trong enums: mục tiêu của nó sẽ trở thành thành viên.

Added in version 3.11.

@enum.nonmember¶: Một công cụ trang trí để sử dụng trong enums: mục tiêu của nó sẽ không trở thành thành viên.

Added in version 3.11.

@enum.global_enum¶: Một công cụ trang trí để thay đổi str() và repr() của một enum để hiển thị các thành viên của nó thuộc về mô-đun thay vì lớp của nó. Chỉ nên sử dụng khi các thành viên enum được xuất sang không gian tên chung của mô-đun (xem ví dụ về re.RegexFlag).

Added in version 3.11.

enum.show_flag_values(value)¶: Trả về danh sách tất cả các số nguyên lũy thừa hai có trong cờ value.

Added in version 3.11.

enum.bin(num, max_bits=None)¶

Giống như bin() tích hợp, ngoại trừ các giá trị âm được biểu thị dưới dạng phần bù hai và bit đầu luôn biểu thị dấu (0 ngụ ý dương, 1 ngụ ý âm).

>>> import enum
>>> enum.bin(10)
'0b0 1010'
>>> enum.bin(~10)   # ~10 is -11
'0b1 0101'

Added in version 3.11.

Ghi chú¶

IntEnum, StrEnum và IntFlag

Ba loại enum này được thiết kế để thay thế cho các giá trị dựa trên chuỗi và số nguyên hiện có; như vậy, chúng có thêm những hạn chế:

__str__ sử dụng giá trị chứ không phải tên của thành viên enum

__format__, vì nó sử dụng __str__ nên cũng sẽ sử dụng giá trị của thành viên enum thay vì tên của nó

Nếu bạn không cần/muốn những hạn chế đó, bạn có thể tạo lớp cơ sở của riêng mình bằng cách tự trộn loại int hoặc str:
>>> từ nhập enum Enum
>>> lớp MyIntEnum(int, Enum):
... vượt qua
hoặc bạn có thể gán lại str() thích hợp, v.v., trong enum của bạn
>>> from enum import Enum, IntEnum
>>> lớp MyIntEnum(IntEnum):
... __str__ = Enum.__str__

`enum` --- Hỗ trợ liệt kê¶

Nội dung mô-đun¶

Các kiểu dữ liệu¶

Tên `dunder` được hỗ trợ¶

Tên `_sunder_` được hỗ trợ¶

Tiện ích và trang trí¶

Ghi chú¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

enum --- Hỗ trợ liệt kê¶

Nội dung mô-đun¶

Các kiểu dữ liệu¶

Tên __dunder__ được hỗ trợ¶

Tên _sunder_ được hỗ trợ¶

Tiện ích và trang trí¶

Ghi chú¶

`enum` --- Hỗ trợ liệt kê¶

Tên `dunder` được hỗ trợ¶

Tên `_sunder_` được hỗ trợ¶