enum — Поддержка перечислений

Содержание модуля

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, позволяющее более точно управлять тем, как обрабатываются недопустимые значения в перечислении.

auto

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

property()

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

unique()

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

verify()

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

member()

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

nonmember()

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

global_enum()

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

show_flag_values()

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

Типы данных

class enum.EnumType

EnumType — это метакласс для перечислений enum. Возможна переопределение EnumType — см. Наследование EnumType для подробностей.

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

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

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

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

  cls:

  Класс перечисления, который вызывается.

  value:

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

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

  cls:

  Класс перечисления, который вызывается.

  value:

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

  names:

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

  module:

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

  qualname:

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

  type:

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

  start:

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

  boundary:

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

__contains__(cls, member)

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

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

Изменено в версии 3.12: До Python 3.12, 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)

Возвращает член перечисления в 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__

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

__reversed__(cls)

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

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

_add_alias_()

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

_add_value_alias_()

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

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

class enum.Enum

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

name

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

>>> Color.BLUE.name
'BLUE'

value

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

>>> Color.RED.value
1

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

Примечание

Значения членов перечисления

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

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

_name_

Имя члена.

_value_

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

_order_

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

_ignore_

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

_ignore_ — список имён, которые не станут членами и чьи имена также будут удалены из завершённого перечисления. Пример см. в TimePeriod.

__dir__(self)

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

>>> from datetime import date
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @classmethod
...     def today(cls):
...         print('today is %s' % cls(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:

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

count:

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

last_values:

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

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

>>> from enum import auto
>>> 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

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

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

_missing_(cls, value)

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

>>> from enum import 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'>

__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(). По умолчанию возвращает имя перечисления, имя члена и значение, но может быть переопределено:

>>> 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(). По умолчанию возвращает имя перечисления и имя члена, но может быть переопределено:

>>> 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__(), но может быть переопределено:

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

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 или с ним, не является частью перечисления.

Примечание

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

Примечание

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

Примечание

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

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

class enum.Flag

Flag это то же самое, что и Enum, но его члены поддерживают побитовые операторы & (И), | (ИЛИ), ^ (Исключающее ИЛИ) и ~ (НЕ); результаты этих операций являются (псевдонимами) членами перечисления.

__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.11.

__len__(self):

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

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

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

__bool__(self):

Возвращает True, если в флаге есть какие-либо члены, в противном случае False:

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

__or__(self, other)

Возвращает текущий флаг, побитовое ИЛИ с другим:

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

__and__(self, other)

Возвращает текущий флаг, побитовое И с другим:

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

__xor__(self, other)

Возвращает текущий флаг, побитовое ИСКЛЮЧАЮЩЕЕ ИЛИ с другим:

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

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

• результат является допустимым 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.11.

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

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>

Утилиты и декораторы

class enum.auto

auto может быть использовано вместо значения. Если используется, механизм Enum вызовет Enum’s _generate_next_value_() для получения соответствующего значения. Для 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.11.

@enum.unique

Декоратор класса специально для перечислений. Он ищет псевдонимы в __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

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

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

@enum.member

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

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

@enum.nonmember

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

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

@enum.global_enum

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

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

enum.show_flag_values(value)

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

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

Примечания

IntEnum, StrEnum и IntFlag

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

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

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

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

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

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