`enum.md`

958 строк · 47.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/library/enum.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `enum` – Поддержка перечислений89Добавлено в версии 3.4.1011**Исходный код:** [Lib/enum.py](https://python-all.ru/src/3.12/Lib/enum.py)1213Важно1415На этой странице содержится справочная информация по API. Обучающую информацию и обсуждение более сложных тем см. в1617- [Базовое руководство](https://python-all.ru/3.12/howto/enum.html#enum-basic-tutorial)18- [Продвинутое руководство](https://python-all.ru/3.12/howto/enum.html#enum-advanced-tutorial)19- [Кулинарная книга Enum](https://python-all.ru/3.12/howto/enum.html#enum-cookbook)2021---2223Перечисление:2425- это набор символических имён (членов), привязанных к уникальным значениям26- может быть перебрано для возврата канонических (т.е. не псевдонимов) членов в порядке определения27- использует синтаксис *вызова* для возврата членов по значению28- использует синтаксис *индексации* для возврата членов по имени2930Перечисления создаются либо с помощью синтаксиса [`class`](https://python-all.ru/3.12/reference/compound_stmts.html#class), либо с помощью синтаксиса вызова функции:3132```python33>>> from enum import Enum3435>>> # синтаксис класса36>>> class Color(Enum):37...     RED = 138...     GREEN = 239...     BLUE = 34041>>> # функциональный синтаксис42>>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])43```4445Хотя для создания перечислений можно использовать синтаксис [`class`](https://python-all.ru/3.12/reference/compound_stmts.html#class), перечисления не являются обычными классами Python. См. [Чем перечисления отличаются?](https://python-all.ru/3.12/howto/enum.html#enum-class-differences) для получения дополнительной информации.4647> **Примечание**48>49> Терминология50>51> - Класс `Color` является *перечислением* (или *enum*)52> - Атрибуты `Color.RED`, `Color.GREEN` и т.д. являются *членами перечисления* (или *членами*) и по сути являются константами.53> - Члены перечисления имеют *имена* и *значения* (имя `Color.RED` – `RED`, значение `Color.BLUE` – `3` и т.д.)5455---5657## Содержимое модуля5859> [`EnumType`](https://python-all.ru/3.12/library/enum.html#enum.EnumType)60>61> > `type` для Enum и его подклассов.62>63> [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum)64>65> > Базовый класс для создания перечисляемых констант.66>67> [`IntEnum`](https://python-all.ru/3.12/library/enum.html#enum.IntEnum)68>69> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`int`](https://python-all.ru/3.12/library/functions.html#int). ([Примечания](https://python-all.ru/3.12/library/enum.html#notes))70>71> [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum)72>73> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). ([Примечания](https://python-all.ru/3.12/library/enum.html#notes))74>75> [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag)76>77> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag).78>79> [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag)80>81> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операторов без потери их принадлежности к [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag). Члены [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag) также являются подклассами [`int`](https://python-all.ru/3.12/library/functions.html#int). ([Примечания](https://python-all.ru/3.12/library/enum.html#notes))82>83> [`ReprEnum`](https://python-all.ru/3.12/library/enum.html#enum.ReprEnum)84>85> > Используется [`IntEnum`](https://python-all.ru/3.12/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag) для сохранения [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) примешиваемого типа.86>87> [`EnumCheck`](https://python-all.ru/3.12/library/enum.html#enum.EnumCheck)88>89> > Перечисление со значениями `CONTINUOUS`, `NAMED_FLAGS` и `UNIQUE`, для использования с [`verify()`](https://python-all.ru/3.12/library/enum.html#enum.verify), чтобы гарантировать соблюдение различных ограничений для заданного перечисления.90>91> [`FlagBoundary`](https://python-all.ru/3.12/library/enum.html#enum.FlagBoundary)92>93> > Перечисление со значениями `STRICT`, `CONFORM`, `EJECT` и `KEEP`, которое обеспечивает более детальный контроль над обработкой недопустимых значений в перечислении.94>95> [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto)96>97> > Экземпляры заменяются подходящим значением для членов Enum. [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum) по умолчанию принимает значение в нижнем регистре имени члена, в то время как другие перечисления по умолчанию начинаются с 1 и увеличиваются оттуда.98>99> [`property()`](https://python-all.ru/3.12/library/enum.html#enum.property)100>101> > Позволяет членам [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum) иметь атрибуты без конфликта с именами членов. Атрибуты `value` и `name` реализованы таким образом.102>103> [`unique()`](https://python-all.ru/3.12/library/enum.html#enum.unique)104>105> > Декоратор класса перечисления, который гарантирует, что каждому значению соответствует только одно имя.106>107> [`verify()`](https://python-all.ru/3.12/library/enum.html#enum.verify)108>109> > Декоратор класса перечисления, который проверяет выбираемые пользователем ограничения для перечисления.110>111> [`member()`](https://python-all.ru/3.12/library/enum.html#enum.member)112>113> > Превращает `obj` в член. Может использоваться как декоратор.114>115> [`nonmember()`](https://python-all.ru/3.12/library/enum.html#enum.nonmember)116>117> > Не превращает `obj` в член. Может использоваться как декоратор.118>119> [`global_enum()`](https://python-all.ru/3.12/library/enum.html#enum.global_enum)120>121> > Изменяет [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.12/library/functions.html#repr) перечисления, чтобы его члены отображались как принадлежащие модулю, а не его классу, и экспортирует члены перечисления в глобальное пространство имён.122>123> [`show_flag_values()`](https://python-all.ru/3.12/library/enum.html#enum.show_flag_values)124>125> > Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся во флаге.126127Добавлено в версии 3.6: `Flag`, `IntFlag`, `auto`128129Добавлено в версии 3.11: `StrEnum`, `EnumCheck`, `ReprEnum`, `FlagBoundary`, `property`, `member`, `nonmember`, `global_enum`, `show_flag_values`130131---132133## Типы данных134135#### `class enum.EnumType`136137*EnumType* – это [метакласс](https://python-all.ru/3.12/glossary.html#term-metaclass) для перечислений *enum*. Есть возможность создать подкласс *EnumType* – подробнее см. в разделе [Subclassing EnumType](https://python-all.ru/3.12/howto/enum.html#enumtype-examples).138139*EnumType* отвечает за установку правильных `__repr__()`, `__str__()`, `__format__()` и `__reduce__()` методов в финальном *enum*, а также за создание членов перечисления, корректную обработку дубликатов, предоставление возможности итерации по классу перечисления и т.д.140141#### `__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)`142143Этот метод вызывается двумя разными способами:144145- для поиска существующего члена:146147  > **cls:**148  >149  > Вызываемый класс перечисления.150  >151  > **value:**152  >153  > Значение для поиска.154- для использования перечисления `cls` для создания нового перечисления (только если существующее перечисление не имеет членов):155156  > **cls:**157  >158  > Вызываемый класс перечисления.159  >160  > **value:**161  >162  > Имя нового создаваемого перечисления.163  >164  > **names:**165  >166  > Имена/значения членов нового перечисления.167  >168  > **модуль:**169  >170  > Имя модуля, в котором создаётся новое перечисление.171  >172  > **qualname:**173  >174  > Фактическое расположение в модуле, где можно найти это перечисление.175  >176  > **тип:**177  >178  > Примесный тип для нового перечисления.179  >180  > **start:**181  >182  > Первое целое значение для перечисления (используется функцией [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto)).183  >184  > **boundary:**185  >186  > Как обрабатывать значения, выходящие за пределы диапазона в битовых операциях (только для [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag)).187188#### `__contains__(cls, member)`189190Возвращает `True`, если member принадлежит `cls`:191192```python193>>> some_var = Color.RED194>>> some_var in Color195True196>>> Color.RED.value in Color197True198```199200Изменено в версии 3.12: До Python 3.12 при проверке вхождения элемента, не являющегося членом Enum, вызывалось исключение `TypeError`.201202#### `__dir__(cls)`203204Возвращает `['__class__', '__doc__', '__members__', '__module__']` и имена членов в *cls*:205206```python207>>> dir(Color)208['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']209```210211#### `__getitem__(cls, name)`212213Возвращает член Enum из *cls*, соответствующий *name*, или вызывает [`KeyError`](https://python-all.ru/3.12/library/exceptions.html#KeyError):214215```python216>>> Color['BLUE']217<Color.BLUE: 3>218```219220#### `__iter__(cls)`221222Возвращает каждый член из *cls* в порядке определения:223224```python225>>> list(Color)226[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]227```228229#### `__len__(cls)`230231Возвращает количество членов в *cls*:232233```python234>>> len(Color)2353236```237238#### `__members__`239240Возвращает отображение каждого имени enum на его член, включая псевдонимы241242#### `__reversed__(cls)`243244Возвращает каждый член из *cls* в обратном порядке определения:245246```python247>>> list(reversed(Color))248[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]249```250251Добавлено в версии 3.11: До версии 3.11 `enum` использовал тип `EnumMeta`, который сохранён как псевдоним.252253#### `class enum.Enum`254255*Enum* – это базовый класс для всех перечислений *enum*.256257#### `name`258259Имя, используемое для определения члена `Enum`:260261```python262>>> Color.BLUE.name263'BLUE'264```265266#### `value`267268Значение, присвоенное члену `Enum`:269270```python271>>> Color.RED.value2721273```274275Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__new__).276277> **Примечание**278>279> Значения членов Enum280>281> Значения членов могут быть любыми: [`int`](https://python-all.ru/3.12/library/functions.html#int), [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) и т. д. Если точное значение не важно, можно использовать экземпляры [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto), и подходящее значение будет выбрано автоматически. Подробнее см. [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto).282>283> Хотя можно использовать изменяемые/нехешируемые значения, такие как [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict), [`list`](https://python-all.ru/3.12/library/stdtypes.html#list) или изменяемый [`dataclass`](https://python-all.ru/3.12/library/dataclasses.html#dataclasses.dataclass), они будут оказывать квадратичное влияние на производительность при создании по сравнению с общим количеством изменяемых/нехешируемых значений в перечислении.284285#### `_name_`286287Имя члена.288289#### `_value_`290291Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__new__).292293#### `_order_`294295Больше не используется, сохранено для обратной совместимости. (атрибут класса, удаляется при создании класса).296297#### `_ignore_`298299`_ignore_` используется только во время создания и удаляется из перечисления после завершения создания.300301`_ignore_` – это список имён, которые не станут членами, и их имена также будут удалены из готового перечисления. См. пример [TimePeriod](https://python-all.ru/3.12/howto/enum.html#enum-time-period).302303#### `__dir__(self)`304305Возвращает `['__class__', '__doc__', '__module__', 'name', 'value']` и все публичные методы, определённые в *self.\_\_class\_\_*:306307```python308>>> from datetime import date309>>> class Weekday(Enum):310...     MONDAY = 1311...     TUESDAY = 2312...     WEDNESDAY = 3313...     THURSDAY = 4314...     FRIDAY = 5315...     SATURDAY = 6316...     SUNDAY = 7317...     @classmethod318...     def today(cls):319...         print('today is %s' % cls(date.today().isoweekday()).name)320...321>>> dir(Weekday.SATURDAY)322['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']323```324325#### `_generate_next_value_(name, start, count, last_values)`326327> **name:**328>329> Имя определяемого члена (например, 'RED').330>331> **start:**332>333> Начальное значение для Enum; по умолчанию 1.334>335> **count:**336>337> Количество уже определённых членов, не включая текущий.338>339> **last\_values:**340>341> Список предыдущих значений.342343*staticmethod*, используемый для определения следующего значения, возвращаемого [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto):344345```python346>>> from enum import auto347>>> class PowersOfThree(Enum):348...     @staticmethod349...     def _generate_next_value_(name, start, count, last_values):350...         return 3 ** (count + 1)351...     FIRST = auto()352...     SECOND = auto()353...354>>> PowersOfThree.SECOND.value3559356```357358#### `__init__(self, *args, **kwds)`359360По умолчанию ничего не делает. Если в определении члена задано несколько значений, эти значения становятся отдельными аргументами для `__init__`; например:361362```python363>>> from enum import Enum364>>> class Weekday(Enum):365...     MONDAY = 1, 'Mon'366```367368`Weekday.__init__()` будет вызван как `Weekday.__init__(self, 1, 'Mon')`369370#### `__init_subclass__(cls, **kwds)`371372Метод класса *classmethod*, используемый для дальнейшей настройки последующих подклассов. По умолчанию ничего не делает.373374#### `_missing_(cls, value)`375376Метод класса *classmethod* для поиска значений, не найденных в *cls*. По умолчанию он ничего не делает, но может быть переопределён для реализации собственного поиска:377378```python379>>> from enum import StrEnum380>>> class Build(StrEnum):381...     DEBUG = auto()382...     OPTIMIZED = auto()383...     @classmethod384...     def _missing_(cls, value):385...         value = value.lower()386...         for member in cls:387...             if member.value == value:388...                 return member389...         return None390...391>>> Build.DEBUG.value392'debug'393>>> Build('deBUG')394<Build.DEBUG: 'debug'>395```396397#### `__new__(cls, *args, **kwds)`398399По умолчанию не существует. Если указан в определении класса перечисления или в примешиваемом классе (например, `int`), все значения, заданные в определении члена, будут переданы; например:400401```python402>>> from enum import Enum403>>> class MyIntEnum(int, Enum):404...     TWENTYSIX = '1a', 16405```406407приводит к вызову `int('1a', 16)` и значению `26` для члена.408409> **Примечание**410>411> При написании пользовательского `__new__` не используйте `super().__new__` – вместо этого вызывайте соответствующий `__new__`.412413#### `__repr__(self)`414415Возвращает строку, используемую для вызовов *repr()*. По умолчанию возвращает имя *Enum*, имя элемента и значение, но может быть переопределено:416417```python418>>> class OtherStyle(Enum):419...     ALTERNATE = auto()420...     OTHER = auto()421...     SOMETHING_ELSE = auto()422...     def __repr__(self):423...         cls_name = self.__class__.__name__424...         return f'{cls_name}.{self.name}'425...426>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"427(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')428```429430#### `__str__(self)`431432Возвращает строку, используемую для вызовов *str()*. По умолчанию возвращает имя *Enum* и имя элемента, но может быть переопределено:433434```python435>>> class OtherStyle(Enum):436...     ALTERNATE = auto()437...     OTHER = auto()438...     SOMETHING_ELSE = auto()439...     def __str__(self):440...         return f'{self.name}'441...442>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"443(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')444```445446#### `__format__(self)`447448Возвращает строку, используемую для вызовов *format()* и *f-строк*. По умолчанию возвращает возвращаемое значение [`__str__()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__str__), но может быть переопределено:449450```python451>>> class OtherStyle(Enum):452...     ALTERNATE = auto()453...     OTHER = auto()454...     SOMETHING_ELSE = auto()455...     def __format__(self, spec):456...         return f'{self.name}'457...458>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"459(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')460```461462> **Примечание**463>464> Использование [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto) с [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum) даёт целые числа с возрастающим значением, начиная с `1`.465466Изменено в версии 3.12: Добавлена [поддержка dataclass](https://python-all.ru/3.12/howto/enum.html#enum-dataclass-support)467468#### `class enum.IntEnum`469470*IntEnum* – то же самое, что *Enum*, но его элементы также являются целыми числами и могут использоваться везде, где используется целое число. Если над элементом *IntEnum* выполняется какая-либо целочисленная операция, результирующее значение теряет статус элемента перечисления.471472```python473>>> from enum import IntEnum474>>> class Number(IntEnum):475...     ONE = 1476...     TWO = 2477...     THREE = 3478...479>>> Number.THREE480<Number.THREE: 3>481>>> Number.ONE + Number.TWO4823483>>> Number.THREE + 54848485>>> Number.THREE == 3486True487```488489> **Примечание**490>491> Использование [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto) с [`IntEnum`](https://python-all.ru/3.12/library/enum.html#enum.IntEnum) даёт целые числа с возрастающим значением, начиная с `1`.492493Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__str__) теперь `int.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__format__) уже был `int.__format__()` по той же причине.494495#### `class enum.StrEnum`496497*StrEnum* – то же самое, что *Enum*, но его элементы также являются строками и могут использоваться в большинстве мест, где используется строка. Результат любой строковой операции, выполненной над элементом *StrEnum* или с его участием, не является частью перечисления.498499> **Примечание**500>501> В стандартной библиотеке есть места, где проверяется точное совпадение с [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), а не с подклассом [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) (например, `type(unknown) == str` вместо `isinstance(unknown, str)`), и в таких случаях потребуется использовать `str(StrEnum.member)`.502503> **Примечание**504>505> Использование [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto) с [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum) даёт имя элемента в нижнем регистре в качестве значения.506507> **Примечание**508>509> [`__str__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__str__) – `str.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__format__) также `str.__format__()` по той же причине.510511Добавлено в версии 3.12.512513#### `class enum.Flag`514515`Flag` – то же, что и [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum), но его элементы поддерживают побитовые операторы `&` (*AND*), `|` (*OR*), `^` (*XOR*) и `~` (*INVERT*); результаты этих операций являются (псевдонимами) элементов перечисления.516517#### `__contains__(self, value)`518519Возвращает *True*, если значение находится в self:520521```python522>>> from enum import Flag, auto523>>> class Color(Flag):524...     RED = auto()525...     GREEN = auto()526...     BLUE = auto()527...528>>> purple = Color.RED | Color.BLUE529>>> white = Color.RED | Color.GREEN | Color.BLUE530>>> Color.GREEN in purple531False532>>> Color.GREEN in white533True534>>> purple in white535True536>>> white in purple537False538```539540#### `__iter__(self):`541542Возвращает все содержащиеся элементы, не являющиеся псевдонимами:543544```python545>>> list(Color.RED)546[<Color.RED: 1>]547>>> list(purple)548[<Color.RED: 1>, <Color.BLUE: 4>]549```550551Добавлено в версии 3.12.552553#### `__len__(self):`554555Возвращает количество элементов во флаге:556557```python558>>> len(Color.GREEN)5591560>>> len(white)5613562```563564Добавлено в версии 3.12.565566#### `__bool__(self):`567568Возвращает *True*, если в флаге есть хотя бы один элемент, иначе *False*:569570```python571>>> bool(Color.GREEN)572True573>>> bool(white)574True575>>> black = Color(0)576>>> bool(black)577False578```579580#### `__or__(self, other)`581582Возвращает текущий флаг, логически сложенный (OR) с другим:583584```python585>>> Color.RED | Color.GREEN586<Color.RED|GREEN: 3>587```588589#### `__and__(self, other)`590591Возвращает текущий флаг, логически умноженный (AND) с другим:592593```python594>>> purple & white595<Color.RED|BLUE: 5>596>>> purple & Color.GREEN597<Color: 0>598```599600#### `__xor__(self, other)`601602Возвращает текущий флаг, логически сложенный по исключающему ИЛИ (XOR) с другим:603604```python605>>> purple ^ white606<Color.GREEN: 2>607>>> purple ^ Color.GREEN608<Color.RED|GREEN|BLUE: 7>609```610611#### `__invert__(self):`612613Возвращает все флаги из *type(self)*, которых нет в self:614615```python616>>> ~white617<Color: 0>618>>> ~purple619<Color.GREEN: 2>620>>> ~Color.RED621<Color.GREEN|BLUE: 6>622```623624#### `_numeric_repr_()`625626Функция, используемая для форматирования оставшихся безымянных числовых значений. По умолчанию – repr значения; распространённые варианты: [`hex()`](https://python-all.ru/3.12/library/functions.html#hex) и [`oct()`](https://python-all.ru/3.12/library/functions.html#oct).627628> **Примечание**629>630> Использование [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto) с [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag) даёт целые числа, являющиеся степенями двойки, начиная с `1`.631632Изменено в версии 3.11: *repr()* флагов с нулевым значением изменилась. Теперь это::633634```python635>>> Color(0)636<Color: 0>637```638639#### `class enum.IntFlag`640641*IntFlag* – то же самое, что *Flag*, но его элементы также являются целыми числами и могут использоваться везде, где используется целое число.642643```python644>>> from enum import IntFlag, auto645>>> class Color(IntFlag):646...     RED = auto()647...     GREEN = auto()648...     BLUE = auto()649...650>>> Color.RED & 2651<Color: 0>652>>> Color.RED | 2653<Color.RED|GREEN: 3>654```655656Если к члену *IntFlag* применяется целочисленная операция, результат не будет *IntFlag*:657658```python659>>> Color.RED + 26603661```662663Если операция *Flag* выполняется с элементом *IntFlag* и:664665- результат является допустимым *IntFlag*: возвращается *IntFlag*666- результат не является допустимым *IntFlag*: результат зависит от настройки *FlagBoundary*667668*repr()* безымянных флагов с нулевым значением изменился. Теперь он:669670```python671>>> Color(0)672<Color: 0>673```674675> **Примечание**676>677> Использование [`auto`](https://python-all.ru/3.12/library/enum.html#enum.auto) с [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag) даёт целые числа, являющиеся степенями двойки, начиная с `1`.678679Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__str__) теперь `int.__str__()` для лучшей поддержки сценария *замены существующих констант*. [`__format__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__format__) уже было `int.__format__()` по той же причине.680681Инверсия `IntFlag` теперь возвращает положительное значение – объединение всех флагов, не входящих в заданный флаг, вместо отрицательного значения. Это соответствует существующему поведению [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag).682683#### `class enum.ReprEnum`684685`ReprEnum` использует [`repr()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__repr__) от [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum), но [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) от примешиваемого типа данных:686687- `int.__str__()` для [`IntEnum`](https://python-all.ru/3.12/library/enum.html#enum.IntEnum) и [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag)688- `str.__str__()` для [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum)689690Наследуйте от `ReprEnum`, чтобы сохранить [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) / [`format()`](https://python-all.ru/3.12/library/functions.html#format) примешиваемого типа данных вместо использования [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum)-умолчания [`str()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__str__).691692Добавлено в версии 3.12.693694#### `class enum.EnumCheck`695696*EnumCheck* содержит параметры, используемые декоратором [`verify()`](https://python-all.ru/3.12/library/enum.html#enum.verify) для проверки различных ограничений; нарушение ограничений приводит к [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).697698#### `UNIQUE`699700Гарантирует, что каждое значение имеет только одно имя:701702```python703>>> from enum import Enum, verify, UNIQUE704>>> @verify(UNIQUE)705... class Color(Enum):706...     RED = 1707...     GREEN = 2708...     BLUE = 3709...     CRIMSON = 1710Traceback (most recent call last):711...712ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED713```714715#### `CONTINUOUS`716717Убедитесь, что между членом с наименьшим значением и членом с наибольшим значением нет пропущенных значений:718719```python720>>> from enum import Enum, verify, CONTINUOUS721>>> @verify(CONTINUOUS)722... class Color(Enum):723...     RED = 1724...     GREEN = 2725...     BLUE = 5726Traceback (most recent call last):727...728ValueError: invalid enum 'Color': missing values 3, 4729```730731#### `NAMED_FLAGS`732733Убедитесь, что любые группы/маски флагов содержат только именованные флаги – это полезно, когда значения задаются явно, а не генерируются с помощью [`auto()`](https://python-all.ru/3.12/library/enum.html#enum.auto):734735```python736>>> from enum import Flag, verify, NAMED_FLAGS737>>> @verify(NAMED_FLAGS)738... class Color(Flag):739...     RED = 1740...     GREEN = 2741...     BLUE = 4742...     WHITE = 15743...     NEON = 31744Traceback (most recent call last):745...746ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]747```748749> **Примечание**750>751> CONTINUOUS и NAMED\_FLAGS предназначены для работы с членами, имеющими целочисленные значения.752753Добавлено в версии 3.12.754755#### `class enum.FlagBoundary`756757*FlagBoundary* управляет тем, как обрабатываются выходящие за пределы диапазона значения в *Flag* и его подклассах.758759#### `STRICT`760761Значения вне диапазона приводят к возбуждению [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError). Это поведение по умолчанию для [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag):762763```python764>>> from enum import Flag, STRICT, auto765>>> class StrictFlag(Flag, boundary=STRICT):766...     RED = auto()767...     GREEN = auto()768...     BLUE = auto()769...770>>> StrictFlag(2**2 + 2**4)771Traceback (most recent call last):772...773ValueError: <flag 'StrictFlag'> invalid value 20774    given 0b0 10100775  allowed 0b0 00111776```777778#### `CONFORM`779780У выходящих за пределы диапазона значений удаляются недопустимые значения, остаётся допустимое *Flag* значение:781782```python783>>> from enum import Flag, CONFORM, auto784>>> class ConformFlag(Flag, boundary=CONFORM):785...     RED = auto()786...     GREEN = auto()787...     BLUE = auto()788...789>>> ConformFlag(2**2 + 2**4)790<ConformFlag.BLUE: 4>791```792793#### `EJECT`794795Выходящие за пределы диапазона значения теряют членство в *Flag* и возвращаются к [`int`](https://python-all.ru/3.12/library/functions.html#int).796797```python798>>> from enum import Flag, EJECT, auto799>>> class EjectFlag(Flag, boundary=EJECT):800...     RED = auto()801...     GREEN = auto()802...     BLUE = auto()803...804>>> EjectFlag(2**2 + 2**4)80520806```807808#### `KEEP`809810Выходящие за пределы диапазона значения сохраняются, и членство в *Flag* сохраняется. Это значение по умолчанию для [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag):811812```python813>>> from enum import Flag, KEEP, auto814>>> class KeepFlag(Flag, boundary=KEEP):815...     RED = auto()816...     GREEN = auto()817...     BLUE = auto()818...819>>> KeepFlag(2**2 + 2**4)820<KeepFlag.BLUE|16: 20>821```822823Добавлено в версии 3.12.824825---826827### Поддерживаемые `__dunder__` имена828829[`__members__`](https://python-all.ru/3.12/library/enum.html#enum.EnumType.__members__) представляет собой упорядоченное отображение только для чтения элементов `member_name`:`member`. Оно доступно только на уровне класса.830831[`__new__()`](https://python-all.ru/3.12/library/enum.html#enum.Enum.__new__), если указан, должен создавать и возвращать элементы перечисления; также рекомендуется соответствующим образом установить `_value_` элемента. После создания всех элементов он больше не используется.832833### Поддерживаемые `_sunder_` имена834835- [`_name_`](https://python-all.ru/3.12/library/enum.html#enum.Enum._name_) – имя члена836- [`_value_`](https://python-all.ru/3.12/library/enum.html#enum.Enum._value_) – значение члена; может быть задано в `__new__`837- [`_missing_()`](https://python-all.ru/3.12/library/enum.html#enum.Enum._missing_) – функция поиска, используемая, когда значение не найдено; может быть переопределена838- [`_ignore_`](https://python-all.ru/3.12/library/enum.html#enum.Enum._ignore_) – список имен, представленный в виде [`list`](https://python-all.ru/3.12/library/stdtypes.html#list) или [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), которые не будут преобразованы в члены и будут удалены из итогового класса839- [`_order_`](https://python-all.ru/3.12/library/enum.html#enum.Enum._order_) – больше не используется, сохранено для обратной совместимости (атрибут класса, удаляется при создании класса)840- [`_generate_next_value_()`](https://python-all.ru/3.12/library/enum.html#enum.Enum._generate_next_value_) – используется для получения подходящего значения для члена перечисления; может быть переопределен841842  > **Примечание**843  >844  > Для стандартных классов [`Enum`](https://python-all.ru/3.12/library/enum.html#enum.Enum) следующее выбираемое значение равно последнему увиденному значению, увеличенному на единицу.845  >846  > Для классов [`Flag`](https://python-all.ru/3.12/library/enum.html#enum.Flag) следующее выбираемое значение будет следующей по величине степенью двойки, независимо от последнего увиденного значения.847848Добавлено в версии 3.6: `_missing_`, `_order_`, `_generate_next_value_`849850Добавлено в версии 3.7: `_ignore_`851852---853854## Утилиты и декораторы855856#### `class enum.auto`857858*auto* можно использовать вместо значения. Если он используется, механизм *Enum* вызовет у *Enum* [`_generate_next_value_()`](https://python-all.ru/3.12/library/enum.html#enum.Enum._generate_next_value_) для получения подходящего значения. Для *Enum* и *IntEnum* подходящим значением будет последнее значение плюс один; для *Flag* и *IntFlag* это будет первая степень двойки, превышающая наибольшее значение; для *StrEnum* это будет версия имени элемента в нижнем регистре. Следует соблюдать осторожность при смешивании *auto()* с указанными вручную значениями.859860Экземпляры *auto* разрешаются только на верхнем уровне присваивания:861862- `FIRST = auto()` будет работать (auto() заменяется на `1`);863- `SECOND = auto(), -2` будет работать (auto заменяется на `2`, поэтому `2, -2` используется для создания элемента перечисления `SECOND`;864- `THREE = [auto(), -3]` *не* будет работать (`<auto instance>, -3` используется для создания элемента перечисления `THREE`)865866Изменено в версии 3.11.1: В предыдущих версиях `auto()` должен был быть единственным на строке присваивания, чтобы работать правильно.867868`_generate_next_value_` можно переопределить, чтобы настроить значения, используемые *auto*.869870> **Примечание**871>872> в версии 3.13 `_generate_next_value_` по умолчанию всегда будет возвращать наибольшее значение элемента, увеличенное на 1, и будет выдавать ошибку, если какой-либо элемент имеет несовместимый тип.873874#### `@enum.property`875876Декоратор, похожий на встроенный *property*, но специально для перечислений. Он позволяет атрибутам элементов иметь те же имена, что и сами элементы.877878> **Примечание**879>880> декоратор *property* и элемент должны быть определены в разных классах; например, атрибуты *value* и *name* определены в классе *Enum*, а подклассы *Enum* могут определять элементы с именами `value` и `name`.881882Добавлено в версии 3.12.883884#### `@enum.unique`885886Декоратор [`class`](https://python-all.ru/3.12/reference/compound_stmts.html#class), специально предназначенный для перечислений. Он просматривает [`__members__`](https://python-all.ru/3.12/library/enum.html#enum.EnumType.__members__) перечисления, собирая все найденные псевдонимы; если какие-либо найдены, вызывается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) с подробностями:887888```python889>>> from enum import Enum, unique890>>> @unique891... class Mistake(Enum):892...     ONE = 1893...     TWO = 2894...     THREE = 3895...     FOUR = 3896...897Traceback (most recent call last):898...899ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE900```901902#### `@enum.verify`903904Декоратор [`class`](https://python-all.ru/3.12/reference/compound_stmts.html#class), специально предназначенный для перечислений. Элементы из [`EnumCheck`](https://python-all.ru/3.12/library/enum.html#enum.EnumCheck) используются для указания, какие ограничения должны проверяться в декорированном перечислении.905906Добавлено в версии 3.12.907908#### `@enum.member`909910Декоратор для использования в перечислениях: его цель станет элементом.911912Добавлено в версии 3.12.913914#### `@enum.nonmember`915916Декоратор для использования в перечислениях: его цель не станет элементом.917918Добавлено в версии 3.12.919920#### `@enum.global_enum`921922Декоратор, изменяющий [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.12/library/functions.html#repr) перечисления, чтобы показывать его элементы как принадлежащие модулю, а не классу. Должен использоваться только когда элементы перечисления экспортируются в глобальное пространство имён модуля (см. пример [`re.RegexFlag`](https://python-all.ru/3.12/library/re.html#re.RegexFlag)).923924Добавлено в версии 3.12.925926#### `enum.show_flag_values(value)`927928Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся в *значении* флага.929930Добавлено в версии 3.12.931932---933934## Примечания935936[`IntEnum`](https://python-all.ru/3.12/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.12/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.12/library/enum.html#enum.IntFlag)937938> Эти три типа перечислений предназначены для прямой замены существующих целочисленных и строковых значений; поэтому у них есть дополнительные ограничения:939>940> - `__str__` использует значение, а не имя элемента перечисления941> - `__format__`, поскольку он использует `__str__`, также будет использовать значение элемента перечисления, а не его имя942>943> Если эти ограничения не нужны или нежелательны, можно либо создать свой собственный базовый класс, смешав в нём типы `int` или `str`:944>945> ```python946> >>> from enum import Enum947> >>> class MyIntEnum(int, Enum):948> ...     pass949> ```950>951> или можно переназначить соответствующее [`str()`](https://python-all.ru/3.12/library/stdtypes.html#str) и т.д. в своём перечислении:952>953> ```python954> >>> from enum import Enum, IntEnum955> >>> class MyIntEnum(IntEnum):956> ...     __str__ = Enum.__str__957> ```958