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

auto

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

property()

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

unique()

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

verify()

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

member()

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

nonmember()

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

global_enum()

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

show_flag_values()

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

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

class enum.EnumType¶

EnumType – это метакласс для перечислений enum. Есть возможность создать подкласс EnumType – подробнее см. в разделе Subclassing 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:

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

  модуль:

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

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

Добавлено в версии 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.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

Если операция 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.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>

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

class enum.auto¶

auto можно использовать вместо значения. Если он используется, механизм Enum вызовет у Enum _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.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.

Примечания¶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__