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

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

Примечание

В Python 3.12 можно будет проверять значения членов, а не только сами члены; до тех пор при проверке вхождения будет вызвана ошибка TypeError, если используется не член Enum.

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

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

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

__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

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

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

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

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

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

__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-string. По умолчанию возвращает значение __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__() теперь str.__str__() для более эффективной поддержки сценария замены существующих констант. По той же причине __format__() также 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: Представление 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)

Возвращает список всех целых чисел — степеней двойки, входящих в 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__