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

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

EnumType

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

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

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

verify()

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

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

Добавлена в версии 3.11: До 3.11 enum использовал тип 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:

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

count:

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

last_values:

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

staticmethod, используемый для определения следующего значения, возвращаемого 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)

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

_missing_(cls, value)

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

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

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

Представление нулевого флага без имени изменилось. Теперь оно выглядит так:

>>> 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 вызовет _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.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 самостоятельно:

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

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

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