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

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

property()

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

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

Примечание

В 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__']

__getattr__(cls, name)

Возвращает члена перечисления в cls, соответствующего name, или вызывает исключение AttributeError:

>>> Color.GREEN
<Color.GREEN: 2>

__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

__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

Примечание

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

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

_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

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

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

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

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

Новое в версии 3.11.

class enum.Flag

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

__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

__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 will work (auto is replaced with 2, so 2, -2 is

  используется для создания члена перечисления 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.

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

New in version 3.11.

@enum.member

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

New in version 3.11.

@enum.nonmember

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

New in version 3.11.

@enum.global_enum

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

New in version 3.11.

enum.show_flag_values(value)

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

New in version 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__