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:

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

  names:

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

  module:

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

  qualname:

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

  type:

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

  start:

  Первое целочисленное значение для Enum (используется в 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 при проверке вхождения не являющегося членом 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__

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

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

Примечание

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

Значениями членов могут быть любые объекты: 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, если value содержится в 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

Если с членом 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.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

Декоратор 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.11.

@enum.member

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

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

@enum.nonmember

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

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

@enum.global_enum

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

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

enum.show_flag_values(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__