enum – Поддержка перечислений¶enum – Support for enumerations

Содержимое модуля¶Module contents

EnumType

type для Enum и его подклассов.

Enum

Базовый класс для создания перечисляемых констант.

IntEnum

Базовый класс для создания перечисляемых констант, которые также являются подклассами int. (Примечания)

StrEnum

Базовый класс для создания перечисляемых констант, которые также являются подклассами str. (Примечания)

Flag

Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к Flag.

IntFlag

Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операторов без потери их принадлежности к IntFlag. Члены IntFlag также являются подклассами int. (Примечания)

ReprEnum

Используется IntEnum, StrEnum и IntFlag для сохранения str() примешиваемого типа.

EnumCheck

Перечисление со значениями CONTINUOUS, NAMED_FLAGS и UNIQUE, для использования с verify(), чтобы гарантировать соблюдение различных ограничений для заданного перечисления.

FlagBoundary

Перечисление со значениями STRICT, CONFORM, EJECT и KEEP, которое обеспечивает более детальный контроль над обработкой недопустимых значений в перечислении.

EnumDict

Подкласс dict для использования при создании подкласса EnumType.

auto

Экземпляры заменяются подходящим значением для членов Enum. StrEnum по умолчанию принимает значение в нижнем регистре имени члена, в то время как другие перечисления по умолчанию начинаются с 1 и увеличиваются оттуда.

property()

Позволяет членам Enum иметь атрибуты без конфликта с именами членов. Атрибуты value и name реализованы таким образом.

unique()

Декоратор класса перечисления, который гарантирует, что каждому значению соответствует только одно имя.

verify()

Декоратор класса перечисления, который проверяет выбираемые пользователем ограничения для перечисления.

member()

Превращает obj в член. Может использоваться как декоратор.

nonmember()

Не превращает obj в член. Может использоваться как декоратор.

global_enum()

Изменяет str() и repr() перечисления, чтобы его члены отображались как принадлежащие модулю, а не его классу, и экспортирует члены перечисления в глобальное пространство имён.

show_flag_values()

Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся во флаге.

enum.bin()

Как встроенная bin(), за исключением того, что отрицательные значения представляются в dополнительном коде, и старший бит всегда указывает знак (0 означает положительное, 1 – отрицательное).

Типы данных¶Data types

class enum.EnumType¶

EnumType – это метакласс для перечислений enum. Есть возможность создать подкласс EnumType – подробнее см. в разделе Subclassing EnumType.

EnumType отвечает за установку правильных методов __repr__(), __str__(), __format__() и __reduce__() в конечном перечислении enum, а также за создание членов перечисления, корректную обработку дубликатов, обеспечение итерации по классу перечисления и т.д.

Добавлено в версии 3.11: До версии 3.11 EnumType назывался EnumMeta, который всё ещё доступен как псевдоним.

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

Этот метод вызывается двумя разными способами:

• для поиска существующего члена:

  cls:

  Вызываемый класс перечисления.

  value:

  Значение для поиска.

• для использования перечисления cls для создания нового перечисления (только если существующее перечисление не имеет членов):

  cls:

  Вызываемый класс перечисления.

  value:

  Имя нового создаваемого перечисления.

  names:

  Имена/значения членов нового перечисления.

  модуль:

  Имя модуля, в котором создаётся новое перечисление.

  qualname:

  Фактическое расположение в модуле, где можно найти это перечисление.

  тип:

  Примесный тип для нового перечисления.

  start:

  Первое целое значение для перечисления (используется функцией auto).

  boundary:

  Как обрабатывать значения, выходящие за пределы диапазона в битовых операциях (только для Flag).

__contains__(cls, member)¶

Возвращает True, если member принадлежит cls:

>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True

Изменено в версии 3.12: До Python 3.12 при проверке вхождения элемента, не являющегося членом Enum, вызывалось исключение TypeError.

__dir__(cls)¶

Возвращает ['__class__', '__doc__', '__members__', '__module__'] и имена членов в cls:

>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']

__getitem__(cls, name)¶

Возвращает член Enum из cls, соответствующий name, или вызывает KeyError:

>>> Color['BLUE']
<Color.BLUE: 3>

__iter__(cls)¶

Возвращает каждый член из cls в порядке определения:

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

__len__(cls)¶

Возвращает количество членов в cls:

>>> len(Color)
3

__members__¶

Возвращает отображение каждого имени enum на его член, включая псевдонимы

__reversed__(cls)¶

Возвращает каждый член из cls в обратном порядке определения:

>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

class enum.Enum¶

Enum – это базовый класс для всех перечислений enum.

name¶

Имя, используемое для определения члена Enum:

>>> Color.BLUE.name
'BLUE'

value¶

Значение, присвоенное члену Enum:

>>> Color.RED.value
1

Значение члена; может быть задано в __new__().

Примечание

Значения членов Enum

Значения членов могут быть любыми: int, str и т. д. Если точное значение не важно, можно использовать экземпляры auto, и подходящее значение будет выбрано автоматически. Подробнее см. auto.

Хотя можно использовать изменяемые/нехешируемые значения, такие как dict, list или изменяемый dataclass, они будут оказывать квадратичное влияние на производительность при создании по сравнению с общим количеством изменяемых/нехешируемых значений в перечислении.

_name_¶

Имя члена.

_value_¶

Значение члена; может быть задано в __new__().

_order_¶

Больше не используется, сохранено для обратной совместимости. (атрибут класса, удаляется при создании класса).

Атрибут _order_ может быть указан, чтобы помочь синхронизировать код Python 2 и Python 3. Он будет сверяться с фактическим порядком перечисления и вызывать ошибку, если они не совпадают:

>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
   ['RED', 'BLUE', 'GREEN']
   ['RED', 'GREEN', 'BLUE']

Примечание

В коде Python 2 атрибут _order_ необходим, поскольку порядок определения теряется до того, как его можно зафиксировать.

Добавлено в версии 3.6.

_ignore_¶

_ignore_ используется только во время создания и удаляется из перечисления после завершения создания.

_ignore_ – это список имён, которые не станут членами, и их имена также будут удалены из готового перечисления. См. пример TimePeriod.

Добавлено в версии 3.7.

__dir__(self)¶

Возвращает ['__class__', '__doc__', '__module__', 'name', 'value'] и все публичные методы, определённые в self.__class__:

>>> from enum import Enum
>>> import datetime as dt
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @classmethod
...     def today(cls):
...         print(f'today is {cls(dt.date.today().isoweekday()).name}')
...
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']

_generate_next_value_(name, start, count, last_values)¶

name:

Имя определяемого члена (например, 'RED').

start:

Начальное значение для Enum; по умолчанию 1.

count:

Количество уже определённых членов, не включая текущий.

last_values:

Список предыдущих значений.

Метод staticmethod, используемый для определения следующего значения, возвращаемого auto.

Примечание

Для стандартных классов Enum следующее выбираемое значение – это максимальное увиденное значение, увеличенное на единицу.

Для классов Flag следующее выбираемое значение будет следующей по величине степенью двойки.

Этот метод может быть переопределён, например:

>>> from enum import auto, Enum
>>> class PowersOfThree(Enum):
...     @staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return 3 ** (count + 1)
...     FIRST = auto()
...     SECOND = auto()
...
>>> PowersOfThree.SECOND.value
9

Добавлено в версии 3.6.

Изменено в версии 3.13: В предыдущих версиях использовалось последнее увиденное значение вместо наибольшего.

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

По умолчанию ничего не делает. Если в определении члена задано несколько значений, эти значения становятся отдельными аргументами для __init__; например:

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

Weekday.__init__() будет вызван как Weekday.__init__(self, 1, 'Mon')

__init_subclass__(cls, **kwds)¶

Метод класса classmethod, используемый для дальнейшей настройки последующих подклассов. По умолчанию ничего не делает.

_missing_(cls, value)¶

Метод класса classmethod для поиска значений, не найденных в cls. По умолчанию он ничего не делает, но может быть переопределён для реализации собственного поиска:

>>> from enum import auto, StrEnum
>>> class Build(StrEnum):
...     DEBUG = auto()
...     OPTIMIZED = auto()
...     @classmethod
...     def _missing_(cls, value):
...         value = value.lower()
...         for member in cls:
...             if member.value == value:
...                 return member
...         return None
...
>>> Build.DEBUG.value
'debug'
>>> Build('deBUG')
<Build.DEBUG: 'debug'>

Добавлено в версии 3.6.

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

По умолчанию не существует. Если указан в определении класса перечисления или в примешиваемом классе (например, int), все значения, заданные в определении члена, будут переданы; например:

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

приводит к вызову int('1a', 16) и значению 26 для члена.

Примечание

При написании пользовательского __new__ не используйте super().__new__ – вместо этого вызывайте соответствующий __new__.

__repr__(self)¶

Возвращает строку, используемую для вызовов repr(). По умолчанию возвращает имя Enum, имя элемента и значение, но может быть переопределено:

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __repr__(self):
...         cls_name = self.__class__.__name__
...         return f'{cls_name}.{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')

__str__(self)¶

Возвращает строку, используемую для вызовов str(). По умолчанию возвращает имя Enum и имя элемента, но может быть переопределено:

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __str__(self):
...         return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')

__format__(self)¶

Возвращает строку, используемую для вызовов format() и f-строк. По умолчанию возвращает возвращаемое значение __str__(), но может быть переопределено:

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __format__(self, spec):
...         return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

Примечание

Использование auto с Enum даёт целые числа с возрастающим значением, начиная с 1.

Изменено в версии 3.12: Добавлена поддержка dataclass

_add_alias_()¶

Добавляет новое имя как псевдоним существующего элемента:

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

Вызывает NameError, если имя уже назначено другому элементу.

Добавлено в версии 3.13.

_add_value_alias_()¶

Добавляет новое значение как псевдоним существующего элемента:

>>> Color.RED._add_value_alias_(42)
>>> Color(42)
<Color.RED: 1>

Вызывает ValueError, если значение уже связано с другим элементом.

Пример см. в MultiValueEnum.

Добавлено в версии 3.13.

class enum.IntEnum¶

IntEnum – то же, что и Enum, но его элементы также являются целыми числами и могут использоваться везде, где можно использовать целое число. Если над элементом IntEnum выполняется какая-либо целочисленная операция, результирующее значение теряет статус перечисления.

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

Примечание

Использование auto с IntEnum даёт целые числа с возрастающим значением, начиная с 1.

Изменено в версии 3.11: __str__() теперь int.__str__(), чтобы лучше поддерживать вариант использования замены существующих констант. __format__() уже был int.__format__() по той же причине.

class enum.StrEnum¶

StrEnum – то же, что и Enum, но его элементы также являются строками и могут использоваться почти везде, где можно использовать строку. Результат любой строковой операции, выполненной над элементом StrEnum или с его участием, не является частью перечисления.

>>> 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'

Примечание

В стандартной библиотеке есть места, где проверяется точное совпадение с str, а не с подклассом str (например, type(unknown) == str вместо isinstance(unknown, str)), и в таких случаях потребуется использовать str(MyStrEnum.MY_MEMBER).

Примечание

Использование auto с StrEnum даёт имя элемента в нижнем регистре в качестве значения.

Примечание

__str__() – str.__str__(), чтобы лучше поддерживать вариант использования замены существующих констант. __format__() также str.__format__() по той же причине.

Добавлено в версии 3.12.

class enum.Flag¶

Flag – то же, что и Enum, но его элементы поддерживают побитовые операторы & (AND), | (OR), ^ (XOR) и ~ (INVERT); результаты этих операций являются (псевдонимами) элементов перечисления.

__contains__(self, value)¶

Возвращает True, если значение находится в self:

>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> purple = Color.RED | Color.BLUE
>>> white = Color.RED | Color.GREEN | Color.BLUE
>>> Color.GREEN in purple
False
>>> Color.GREEN in white
True
>>> purple in white
True
>>> white in purple
False

__iter__(self)¶

Возвращает все содержащиеся элементы, не являющиеся псевдонимами:

>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]

Добавлено в версии 3.12.

__len__(self)¶

Возвращает количество элементов во флаге:

>>> len(Color.GREEN)
1
>>> len(white)
3

Добавлено в версии 3.12.

__bool__(self)¶

Возвращает True, если в флаге есть хотя бы один элемент, иначе False:

>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False

__or__(self, other)¶

Возвращает текущий флаг, логически сложенный (OR) с другим:

>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>

__and__(self, other)¶

Возвращает текущий флаг, логически умноженный (AND) с другим:

>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>

__xor__(self, other)¶

Возвращает текущий флаг, логически сложенный по исключающему ИЛИ (XOR) с другим:

>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>

__invert__(self)¶

Возвращает все флаги из type(self), которых нет в self:

>>> ~white
<Color: 0>
>>> ~purple
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>

_numeric_repr_()¶

Функция, используемая для форматирования оставшихся безымянных числовых значений. По умолчанию – repr значения; распространённые варианты: hex() и oct().

Примечание

Использование auto с Flag даёт целые числа, являющиеся степенями двойки, начиная с 1.

Изменено в версии 3.11: repr() флагов с нулевым значением изменилась. Теперь это::

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

class enum.IntFlag¶

IntFlag – то же, что и Flag, но его члены также являются целыми числами и могут использоваться везде, где можно использовать целое число.

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

Если к члену IntFlag применяется целочисленная операция, результат не будет IntFlag:

>>> Color.RED + 2
3

Если к члену IntFlag применяется операция Flag и:

• результат является допустимым IntFlag: возвращается IntFlag

• результат не является допустимым IntFlag: результат зависит от настройки FlagBoundary

repr() безымянных флагов с нулевым значением изменилось. Теперь он:

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

Примечание

Использование auto с IntFlag даёт целые числа, являющиеся степенями двойки, начиная с 1.

Изменено в версии 3.11: __str__() теперь int.__str__() для лучшей поддержки сценария замены существующих констант. __format__() уже было int.__format__() по той же причине.

Инверсия IntFlag теперь возвращает положительное значение – объединение всех флагов, не входящих в заданный флаг, вместо отрицательного значения. Это соответствует существующему поведению Flag.

class enum.ReprEnum¶

ReprEnum использует repr() от Enum, но str() от примешиваемого типа данных:

• int.__str__() для IntEnum и IntFlag

• str.__str__() для StrEnum

Наследуйте от ReprEnum, чтобы сохранить str() / format() примешиваемого типа данных вместо использования Enum-умолчания str().

Добавлено в версии 3.12.

class enum.EnumCheck¶

EnumCheck содержит параметры, используемые декоратором verify() для проверки различных ограничений; нарушение ограничений приводит к ValueError.

UNIQUE¶

Гарантирует, что каждое значение имеет только одно имя:

>>> from enum import Enum, verify, UNIQUE
>>> @verify(UNIQUE)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     CRIMSON = 1
Traceback (most recent call last):
...
ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED

CONTINUOUS¶

Убедитесь, что между членом с наименьшим значением и членом с наибольшим значением нет пропущенных значений:

>>> from enum import Enum, verify, CONTINUOUS
>>> @verify(CONTINUOUS)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 5
Traceback (most recent call last):
...
ValueError: invalid enum 'Color': missing values 3, 4

NAMED_FLAGS¶

Убедитесь, что любые группы/маски флагов содержат только именованные флаги – это полезно, когда значения задаются явно, а не генерируются с помощью auto():

>>> from enum import Flag, verify, NAMED_FLAGS
>>> @verify(NAMED_FLAGS)
... class Color(Flag):
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     WHITE = 15
...     NEON = 31
Traceback (most recent call last):
...
ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]

Примечание

CONTINUOUS и NAMED_FLAGS предназначены для работы с членами, имеющими целочисленные значения.

Добавлено в версии 3.12.

class enum.FlagBoundary¶

FlagBoundary определяет обработку значений, выходящих за пределы диапазона, в Flag и его подклассах.

STRICT¶

Значения вне диапазона приводят к возбуждению ValueError. Это поведение по умолчанию для Flag:

>>> from enum import Flag, STRICT, auto
>>> class StrictFlag(Flag, boundary=STRICT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> StrictFlag(2**2 + 2**4)
Traceback (most recent call last):
...
ValueError: <flag 'StrictFlag'> invalid value 20
    given 0b0 10100
  allowed 0b0 00111

CONFORM¶

Значения вне диапазона очищаются от недопустимых значений, оставляя допустимое значение Flag:

>>> from enum import Flag, CONFORM, auto
>>> class ConformFlag(Flag, boundary=CONFORM):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> ConformFlag(2**2 + 2**4)
<ConformFlag.BLUE: 4>

EJECT¶

Значения вне диапазона теряют членство в Flag и возвращаются к 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¶

Значения вне диапазона сохраняются, и членство в Flag также сохраняется. Это поведение по умолчанию для IntFlag:

>>> from enum import Flag, KEEP, auto
>>> class KeepFlag(Flag, boundary=KEEP):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> KeepFlag(2**2 + 2**4)
<KeepFlag.BLUE|16: 20>

Добавлено в версии 3.12.

class enum.EnumDict¶

EnumDict является подклассом dict, который используется в качестве пространства имен для определения классов перечислений (см. Подготовка пространства имен класса). Он предоставляется для поддержки подклассов EnumType с расширенным поведением, например, с несколькими значениями на одного члена. Его следует вызывать с именем создаваемого класса перечисления, в противном случае частные имена и внутренние классы будут обрабатываться некорректно.

Обратите внимание, что переопределяется только интерфейс MutableMapping (__setitem__() и update()). Возможно обойти проверки с помощью других операций dict, например |=.

member_names¶

Список имен членов.

Добавлено в версии 3.13.

Утилиты и декораторы¶Utilities and decorators

class enum.auto¶

auto можно использовать вместо значения. Если он используется, механизм Enum вызовет _generate_next_value_() объекта Enum, чтобы получить подходящее значение. Для Enum и IntEnum подходящим значением будет последнее значение плюс единица; для Flag и IntFlag – первая степень двойки, превышающая наибольшее значение; для StrEnum – версия имени элемента в нижнем регистре. Следует соблюдать осторожность при смешивании auto() с явно заданными значениями.

Экземпляры auto разрешаются только на верхнем уровне присваивания, отдельно или как часть кортежа:

• FIRST = auto() будет работать (auto() заменяется на 1);

• SECOND = auto(), -2 будет работать (auto заменяется на 2, поэтому 2, -2 используется для создания элемента перечисления SECOND;

• THREE = [auto(), -3] не будет работать ([<auto instance>, -3] используется для создания элемента перечисления THREE)

Изменено в версии 3.11.1: В предыдущих версиях auto() должен был быть единственным на строке присваивания, чтобы работать правильно.

_generate_next_value_ можно переопределить, чтобы настроить значения, используемые auto.

Примечание

в версии 3.13 _generate_next_value_ по умолчанию всегда будет возвращать наибольшее значение элемента, увеличенное на 1, и будет выдавать ошибку, если какой-либо элемент имеет несовместимый тип.

@enum.property¶

Декоратор, похожий на встроенный property, но специально для перечислений. Он позволяет атрибутам элементов иметь те же имена, что и сами элементы.

Примечание

декоратор property и элемент должны быть определены в разных классах; например, атрибуты value и name определены в классе Enum, а подклассы Enum могут определять элементы с именами value и name.

Добавлено в версии 3.12.

@enum.unique¶

Декоратор class, специально предназначенный для перечислений. Он просматривает __members__ перечисления, собирая все найденные псевдонимы; если какие-либо найдены, вызывается ValueError с подробностями:

>>> from enum import Enum, unique
>>> @unique
... class Mistake(Enum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...     FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE

@enum.verify¶

Декоратор class, специально предназначенный для перечислений. Элементы из EnumCheck используются для указания, какие ограничения должны проверяться в декорированном перечислении.

Добавлено в версии 3.12.

@enum.member¶

Декоратор для использования в перечислениях: его цель станет элементом.

Добавлено в версии 3.12.

@enum.nonmember¶

Декоратор для использования в перечислениях: его цель не станет элементом.

Добавлено в версии 3.12.

@enum.global_enum¶

Декоратор, изменяющий str() и repr() перечисления, чтобы показывать его элементы как принадлежащие модулю, а не классу. Должен использоваться только когда элементы перечисления экспортируются в глобальное пространство имён модуля (см. пример re.RegexFlag).

Добавлено в версии 3.12.

enum.show_flag_values(value)¶

Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся в значении флага.

Добавлено в версии 3.12.

enum.bin(num, max_bits=None)¶

Как встроенная bin(), за исключением того, что отрицательные значения представляются в dополнительном коде, и старший бит всегда указывает знак (0 означает положительное, 1 – отрицательное).

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

Добавлено в версии 3.12.

Примечания¶Notes

IntEnum, StrEnum и IntFlag

Эти три типа перечислений предназначены для прямой замены существующих целочисленных и строковых значений; поэтому у них есть дополнительные ограничения:

• __str__ использует значение, а не имя элемента перечисления

• __format__, поскольку он использует __str__, также будет использовать значение элемента перечисления, а не его имя

Если эти ограничения не нужны или нежелательны, можно либо создать свой собственный базовый класс, смешав в нём типы int или str:

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass

или можно переназначить соответствующее str() и т.д. в своём перечислении:

>>> from enum import Enum, IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = Enum.__str__