`enum.md`

919 строк · 45.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/library/enum.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`enum`](https://python-all.ru/3.11/library/enum.html#module-enum) – Поддержка перечислений89Новое в версии 3.4.1011**Исходный код:** [Lib/enum.py](https://python-all.ru/src/3.11/Lib/enum.py)1213Важно1415На этой странице содержится справочная информация по API. Обучающую информацию и обсуждение более сложных тем см. в1617- [Базовое руководство](https://python-all.ru/3.11/howto/enum.html#enum-basic-tutorial)18- [Продвинутое руководство](https://python-all.ru/3.11/howto/enum.html#enum-advanced-tutorial)19- [Кулинарная книга Enum](https://python-all.ru/3.11/howto/enum.html#enum-cookbook)2021---2223Перечисление:2425- это набор символических имён (членов), привязанных к уникальным значениям26- может быть перебрано для возврата канонических (т.е. не псевдонимов) членов в порядке определения27- использует синтаксис *вызова* для возврата членов по значению28- использует синтаксис *индексации* для возврата членов по имени2930Перечисления создаются либо с помощью синтаксиса [`class`](https://python-all.ru/3.11/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', 'GREEN', 'BLUE'])43```4445Хотя для создания перечислений можно использовать синтаксис [`class`](https://python-all.ru/3.11/reference/compound_stmts.html#class), перечисления не являются обычными классами Python. См. [Чем перечисления отличаются?](https://python-all.ru/3.11/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.11/library/enum.html#enum.EnumType)60>61> > `type` для Enum и его подклассов.62>63> [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum)64>65> > Базовый класс для создания перечисляемых констант.66>67> [`IntEnum`](https://python-all.ru/3.11/library/enum.html#enum.IntEnum)68>69> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`int`](https://python-all.ru/3.11/library/functions.html#int). ([Примечания](https://python-all.ru/3.11/library/enum.html#notes))70>71> [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum)72>73> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). ([Примечания](https://python-all.ru/3.11/library/enum.html#notes))74>75> [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag)76>77> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag).78>79> [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag)80>81> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операторов без потери их принадлежности к [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag). Члены [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag) также являются подклассами [`int`](https://python-all.ru/3.11/library/functions.html#int). ([Примечания](https://python-all.ru/3.11/library/enum.html#notes))82>83> [`ReprEnum`](https://python-all.ru/3.11/library/enum.html#enum.ReprEnum)84>85> > Используется [`IntEnum`](https://python-all.ru/3.11/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag) для сохранения [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) примешиваемого типа.86>87> [`EnumCheck`](https://python-all.ru/3.11/library/enum.html#enum.EnumCheck)88>89> > Перечисление со значениями `CONTINUOUS`, `NAMED_FLAGS` и `UNIQUE`, для использования с [`verify()`](https://python-all.ru/3.11/library/enum.html#enum.verify), чтобы гарантировать соблюдение различных ограничений для заданного перечисления.90>91> [`FlagBoundary`](https://python-all.ru/3.11/library/enum.html#enum.FlagBoundary)92>93> > Перечисление со значениями `STRICT`, `CONFORM`, `EJECT` и `KEEP`, которое обеспечивает более детальный контроль над обработкой недопустимых значений в перечислении.94>95> [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto)96>97> > Экземпляры заменяются подходящим значением для членов Enum. [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum) по умолчанию принимает значение в нижнем регистре имени члена, в то время как другие перечисления по умолчанию начинаются с 1 и увеличиваются оттуда.98>99> [`property()`](https://python-all.ru/3.11/library/enum.html#enum.property)100>101> > Позволяет элементам [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum) иметь атрибуты без конфликта с именами элементов.102>103> [`unique()`](https://python-all.ru/3.11/library/enum.html#enum.unique)104>105> > Декоратор класса перечисления, который гарантирует, что каждому значению соответствует только одно имя.106>107> [`verify()`](https://python-all.ru/3.11/library/enum.html#enum.verify)108>109> > Декоратор класса перечисления, который проверяет выбираемые пользователем ограничения для перечисления.110>111> [`member()`](https://python-all.ru/3.11/library/enum.html#enum.member)112>113> > Превращает `obj` в член. Может использоваться как декоратор.114>115> [`nonmember()`](https://python-all.ru/3.11/library/enum.html#enum.nonmember)116>117> > Не превращает `obj` в член. Может использоваться как декоратор.118>119> [`global_enum()`](https://python-all.ru/3.11/library/enum.html#enum.global_enum)120>121> > Изменяет [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.11/library/functions.html#repr) перечисления, чтобы его члены отображались как принадлежащие модулю, а не его классу, и экспортирует члены перечисления в глобальное пространство имён.122>123> [`show_flag_values()`](https://python-all.ru/3.11/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.11/glossary.html#term-metaclass) для перечислений *enum*. Есть возможность создать подкласс *EnumType* – подробнее см. в разделе [Subclassing EnumType](https://python-all.ru/3.11/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.11/library/enum.html#enum.auto)).183  >184  > **boundary:**185  >186  > Как обрабатывать значения, выходящие за пределы диапазона в битовых операциях (только для [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag)).187188#### `__contains__(cls, member)`189190Возвращает `True`, если member принадлежит `cls`:191192```python193>>> some_var = Color.RED194>>> some_var in Color195True196```197198> **Примечание**199>200> Начиная с Python 3.12 можно будет проверять значения элементов, а не только сами элементы; до тех пор при проверке вхождения не-элемента перечисления будет возникать `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#### `__getattr__(cls, name)`212213Возвращает элемент перечисления в *cls*, соответствующий *name*, или вызывает [`AttributeError`](https://python-all.ru/3.11/library/exceptions.html#AttributeError):214215```python216>>> Color.GREEN217<Color.GREEN: 2>218```219220#### `__getitem__(cls, name)`221222Возвращает член Enum из *cls*, соответствующий *name*, или вызывает [`KeyError`](https://python-all.ru/3.11/library/exceptions.html#KeyError):223224```python225>>> Color['BLUE']226<Color.BLUE: 3>227```228229#### `__iter__(cls)`230231Возвращает каждый член из *cls* в порядке определения:232233```python234>>> list(Color)235[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]236```237238#### `__len__(cls)`239240Возвращает количество членов в *cls*:241242```python243>>> len(Color)2443245```246247#### `__reversed__(cls)`248249Возвращает каждый член из *cls* в обратном порядке определения:250251```python252>>> list(reversed(Color))253[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]254```255256Новое в версии 3.11: До версии 3.11 `enum` использовал тип `EnumMeta`, который сохранён как псевдоним.257258#### `class enum.Enum`259260*Enum* – это базовый класс для всех перечислений *enum*.261262#### `name`263264Имя, используемое для определения члена `Enum`:265266```python267>>> Color.BLUE.name268'BLUE'269```270271#### `value`272273Значение, присвоенное члену `Enum`:274275```python276>>> Color.RED.value2771278```279280Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__).281282> **Примечание**283>284> Значения членов Enum285>286> Значения членов могут быть любыми: [`int`](https://python-all.ru/3.11/library/functions.html#int), [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) и т. д. Если точное значение не важно, можно использовать экземпляры [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto), и подходящее значение будет выбрано автоматически. Подробнее см. [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto).287>288> Хотя можно использовать изменяемые/нехешируемые значения, такие как [`dict`](https://python-all.ru/3.11/library/stdtypes.html#dict), [`list`](https://python-all.ru/3.11/library/stdtypes.html#list) или изменяемый [`dataclass`](https://python-all.ru/3.11/library/dataclasses.html#dataclasses.dataclass), они будут оказывать квадратичное влияние на производительность при создании по сравнению с общим количеством изменяемых/нехешируемых значений в перечислении.289290#### `_name_`291292Имя члена.293294#### `_value_`295296Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__).297298#### `_order_`299300Больше не используется, сохранено для обратной совместимости. (атрибут класса, удаляется при создании класса).301302#### `_ignore_`303304`_ignore_` используется только во время создания и удаляется из перечисления после завершения создания.305306`_ignore_` – это список имён, которые не станут членами, и их имена также будут удалены из готового перечисления. См. пример [TimePeriod](https://python-all.ru/3.11/howto/enum.html#enum-time-period).307308#### `__dir__(self)`309310Возвращает `['__class__', '__doc__', '__module__', 'name', 'value']` и все публичные методы, определённые в *self.\_\_class\_\_*:311312```python313>>> from datetime import date314>>> class Weekday(Enum):315...     MONDAY = 1316...     TUESDAY = 2317...     WEDNESDAY = 3318...     THURSDAY = 4319...     FRIDAY = 5320...     SATURDAY = 6321...     SUNDAY = 7322...     @classmethod323...     def today(cls):324...         print('today is %s' % cls(date.today().isoweekday()).name)325>>> dir(Weekday.SATURDAY)326['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']327```328329#### `_generate_next_value_(name, start, count, last_values)`330331> **name:**332>333> Имя определяемого члена (например, 'RED').334>335> **start:**336>337> Начальное значение для Enum; по умолчанию 1.338>339> **count:**340>341> Количество уже определённых членов, не включая текущий.342>343> **last\_values:**344>345> Список предыдущих значений.346347*staticmethod*, используемый для определения следующего значения, возвращаемого [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto):348349```python350>>> from enum import auto351>>> class PowersOfThree(Enum):352...     @staticmethod353...     def _generate_next_value_(name, start, count, last_values):354...         return 3 ** (count + 1)355...     FIRST = auto()356...     SECOND = auto()357>>> PowersOfThree.SECOND.value3589359```360361#### `__init_subclass__(cls, **kwds)`362363Метод класса *classmethod*, используемый для дальнейшей настройки последующих подклассов. По умолчанию ничего не делает.364365#### `_missing_(cls, value)`366367Метод класса *classmethod* для поиска значений, не найденных в *cls*. По умолчанию он ничего не делает, но может быть переопределён для реализации собственного поиска:368369```python370>>> from enum import StrEnum371>>> class Build(StrEnum):372...     DEBUG = auto()373...     OPTIMIZED = auto()374...     @classmethod375...     def _missing_(cls, value):376...         value = value.lower()377...         for member in cls:378...             if member.value == value:379...                 return member380...         return None381>>> Build.DEBUG.value382'debug'383>>> Build('deBUG')384<Build.DEBUG: 'debug'>385```386387#### `__repr__(self)`388389Возвращает строку, используемую для вызовов *repr()*. По умолчанию возвращает имя *Enum*, имя элемента и значение, но может быть переопределено:390391```python392>>> class OtherStyle(Enum):393...     ALTERNATE = auto()394...     OTHER = auto()395...     SOMETHING_ELSE = auto()396...     def __repr__(self):397...         cls_name = self.__class__.__name__398...         return f'{cls_name}.{self.name}'399>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"400(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')401```402403#### `__str__(self)`404405Возвращает строку, используемую для вызовов *str()*. По умолчанию возвращает имя *Enum* и имя элемента, но может быть переопределено:406407```python408>>> class OtherStyle(Enum):409...     ALTERNATE = auto()410...     OTHER = auto()411...     SOMETHING_ELSE = auto()412...     def __str__(self):413...         return f'{self.name}'414>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"415(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')416```417418#### `__format__(self)`419420Возвращает строку, используемую для вызовов *format()* и *f-строк*. По умолчанию возвращает возвращаемое значение [`__str__()`](https://python-all.ru/3.11/library/enum.html#enum.Enum.__str__), но может быть переопределено:421422```python423>>> class OtherStyle(Enum):424...     ALTERNATE = auto()425...     OTHER = auto()426...     SOMETHING_ELSE = auto()427...     def __format__(self, spec):428...         return f'{self.name}'429>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"430(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')431```432433> **Примечание**434>435> Использование [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto) с [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum) даёт целые числа с возрастающим значением, начиная с `1`.436437#### `class enum.IntEnum`438439*IntEnum* – то же самое, что *Enum*, но его элементы также являются целыми числами и могут использоваться везде, где используется целое число. Если над элементом *IntEnum* выполняется какая-либо целочисленная операция, результирующее значение теряет статус элемента перечисления.440441```python442>>> from enum import IntEnum443>>> class Number(IntEnum):444...     ONE = 1445...     TWO = 2446...     THREE = 3447...448>>> Number.THREE449<Number.THREE: 3>450>>> Number.ONE + Number.TWO4513452>>> Number.THREE + 54538454>>> Number.THREE == 3455True456```457458> **Примечание**459>460> Использование [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto) с [`IntEnum`](https://python-all.ru/3.11/library/enum.html#enum.IntEnum) даёт целые числа с возрастающим значением, начиная с `1`.461462Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__str__) теперь `int.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__format__) уже был `int.__format__()` по той же причине.463464#### `class enum.StrEnum`465466*StrEnum* – то же самое, что *Enum*, но его элементы также являются строками и могут использоваться в большинстве мест, где используется строка. Результат любой строковой операции, выполненной над элементом *StrEnum* или с его участием, не является частью перечисления.467468> **Примечание**469>470> В стандартной библиотеке есть места, где проверяется точное совпадение с [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), а не с подклассом [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) (например, `type(unknown) == str` вместо `isinstance(unknown, str)`), и в таких случаях потребуется использовать `str(StrEnum.member)`.471472> **Примечание**473>474> Использование [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto) с [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum) даёт имя элемента в нижнем регистре в качестве значения.475476> **Примечание**477>478> [`__str__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__str__) – `str.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__format__) также `str.__format__()` по той же причине.479480Новое в версии 3.11.481482#### `class enum.Flag`483484Элементы *Flag* поддерживают побитовые операторы `&` (*AND*), `|` (*OR*), `^` (*XOR*) и `~` (*INVERT*); результаты этих операторов являются элементами перечисления.485486#### `__contains__(self, value)`487488Возвращает *True*, если значение находится в self:489490```python491>>> from enum import Flag, auto492>>> class Color(Flag):493...     RED = auto()494...     GREEN = auto()495...     BLUE = auto()496>>> purple = Color.RED | Color.BLUE497>>> white = Color.RED | Color.GREEN | Color.BLUE498>>> Color.GREEN in purple499False500>>> Color.GREEN in white501True502>>> purple in white503True504>>> white in purple505False506```507508#### `__iter__(self):`509510Возвращает все содержащиеся элементы, не являющиеся псевдонимами:511512```python513>>> list(Color.RED)514[<Color.RED: 1>]515>>> list(purple)516[<Color.RED: 1>, <Color.BLUE: 4>]517```518519Новое в версии 3.11.520521#### `__len__(self):`522523Возвращает количество элементов во флаге:524525```python526>>> len(Color.GREEN)5271528>>> len(white)5293530```531532#### `__bool__(self):`533534Возвращает *True*, если в флаге есть хотя бы один элемент, иначе *False*:535536```python537>>> bool(Color.GREEN)538True539>>> bool(white)540True541>>> black = Color(0)542>>> bool(black)543False544```545546#### `__or__(self, other)`547548Возвращает текущий флаг, логически сложенный (OR) с другим:549550```python551>>> Color.RED | Color.GREEN552<Color.RED|GREEN: 3>553```554555#### `__and__(self, other)`556557Возвращает текущий флаг, логически умноженный (AND) с другим:558559```python560>>> purple & white561<Color.RED|BLUE: 5>562>>> purple & Color.GREEN563<Color: 0>564```565566#### `__xor__(self, other)`567568Возвращает текущий флаг, логически сложенный по исключающему ИЛИ (XOR) с другим:569570```python571>>> purple ^ white572<Color.GREEN: 2>573>>> purple ^ Color.GREEN574<Color.RED|GREEN|BLUE: 7>575```576577#### `__invert__(self):`578579Возвращает все флаги из *type(self)*, которых нет в self:580581```python582>>> ~white583<Color: 0>584>>> ~purple585<Color.GREEN: 2>586>>> ~Color.RED587<Color.GREEN|BLUE: 6>588```589590#### `_numeric_repr_()`591592Функция, используемая для форматирования оставшихся безымянных числовых значений. По умолчанию – repr значения; распространённые варианты: [`hex()`](https://python-all.ru/3.11/library/functions.html#hex) и [`oct()`](https://python-all.ru/3.11/library/functions.html#oct).593594> **Примечание**595>596> Использование [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto) с [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag) даёт целые числа, являющиеся степенями двойки, начиная с `1`.597598Изменено в версии 3.11: *repr()* флагов с нулевым значением изменилась. Теперь это::599600```python601>>> Color(0) 602<Color: 0>603```604605#### `class enum.IntFlag`606607*IntFlag* – то же самое, что *Flag*, но его элементы также являются целыми числами и могут использоваться везде, где используется целое число.608609```python610>>> from enum import IntFlag, auto611>>> class Color(IntFlag):612...     RED = auto()613...     GREEN = auto()614...     BLUE = auto()615>>> Color.RED & 2616<Color: 0>617>>> Color.RED | 2618<Color.RED|GREEN: 3>619```620621Если к члену *IntFlag* применяется целочисленная операция, результат не будет *IntFlag*:622623```python624>>> Color.RED + 26253626```627628Если операция *Flag* выполняется с элементом *IntFlag* и:629630- результат является допустимым *IntFlag*: возвращается *IntFlag*631- результат не является допустимым *IntFlag*: результат зависит от настройки *FlagBoundary*632633*repr()* безымянных флагов с нулевым значением изменился. Теперь он:634635```python636>>> Color(0)637<Color: 0>638```639640> **Примечание**641>642> Использование [`auto`](https://python-all.ru/3.11/library/enum.html#enum.auto) с [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag) даёт целые числа, являющиеся степенями двойки, начиная с `1`.643644Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__str__) теперь `int.__str__()` для лучшей поддержки сценария *замены существующих констант*. [`__format__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__format__) уже было `int.__format__()` по той же причине.645646Инверсия `IntFlag` теперь возвращает положительное значение – объединение всех флагов, не входящих в заданный флаг, вместо отрицательного значения. Это соответствует существующему поведению [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag).647648#### `class enum.ReprEnum`649650`ReprEnum` использует [`repr()`](https://python-all.ru/3.11/library/enum.html#enum.Enum.__repr__) от [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum), но [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) от примешиваемого типа данных:651652- `int.__str__()` для [`IntEnum`](https://python-all.ru/3.11/library/enum.html#enum.IntEnum) и [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag)653- `str.__str__()` для [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum)654655Наследуйте от `ReprEnum`, чтобы сохранить [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) / [`format()`](https://python-all.ru/3.11/library/functions.html#format) примешиваемого типа данных вместо использования [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum)-умолчания [`str()`](https://python-all.ru/3.11/library/enum.html#enum.Enum.__str__).656657Новое в версии 3.11.658659#### `class enum.EnumCheck`660661*EnumCheck* содержит параметры, используемые декоратором [`verify()`](https://python-all.ru/3.11/library/enum.html#enum.verify) для проверки различных ограничений; нарушение ограничений приводит к [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError).662663#### `UNIQUE`664665Гарантирует, что каждое значение имеет только одно имя:666667```python668>>> from enum import Enum, verify, UNIQUE669>>> @verify(UNIQUE)670... class Color(Enum):671...     RED = 1672...     GREEN = 2673...     BLUE = 3674...     CRIMSON = 1675Traceback (most recent call last):676...677ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED678```679680#### `CONTINUOUS`681682Убедитесь, что между членом с наименьшим значением и членом с наибольшим значением нет пропущенных значений:683684```python685>>> from enum import Enum, verify, CONTINUOUS686>>> @verify(CONTINUOUS)687... class Color(Enum):688...     RED = 1689...     GREEN = 2690...     BLUE = 5691Traceback (most recent call last):692...693ValueError: invalid enum 'Color': missing values 3, 4694```695696#### `NAMED_FLAGS`697698Убедитесь, что любые группы/маски флагов содержат только именованные флаги – это полезно, когда значения задаются явно, а не генерируются с помощью [`auto()`](https://python-all.ru/3.11/library/enum.html#enum.auto):699700```python701>>> from enum import Flag, verify, NAMED_FLAGS702>>> @verify(NAMED_FLAGS)703... class Color(Flag):704...     RED = 1705...     GREEN = 2706...     BLUE = 4707...     WHITE = 15708...     NEON = 31709Traceback (most recent call last):710...711ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]712```713714> **Примечание**715>716> CONTINUOUS и NAMED\_FLAGS предназначены для работы с членами, имеющими целочисленные значения.717718Новое в версии 3.11.719720#### `class enum.FlagBoundary`721722*FlagBoundary* управляет тем, как обрабатываются выходящие за пределы диапазона значения в *Flag* и его подклассах.723724#### `STRICT`725726Значения вне диапазона приводят к возбуждению [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError). Это поведение по умолчанию для [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag):727728```python729>>> from enum import Flag, STRICT, auto730>>> class StrictFlag(Flag, boundary=STRICT):731...     RED = auto()732...     GREEN = auto()733...     BLUE = auto()734>>> StrictFlag(2**2 + 2**4)735Traceback (most recent call last):736...737ValueError: <flag 'StrictFlag'> invalid value 20738    given 0b0 10100739  allowed 0b0 00111740```741742#### `CONFORM`743744У выходящих за пределы диапазона значений удаляются недопустимые значения, остаётся допустимое *Flag* значение:745746```python747>>> from enum import Flag, CONFORM, auto748>>> class ConformFlag(Flag, boundary=CONFORM):749...     RED = auto()750...     GREEN = auto()751...     BLUE = auto()752>>> ConformFlag(2**2 + 2**4)753<ConformFlag.BLUE: 4>754```755756#### `EJECT`757758Выходящие за пределы диапазона значения теряют членство в *Flag* и возвращаются к [`int`](https://python-all.ru/3.11/library/functions.html#int).759760```python761>>> from enum import Flag, EJECT, auto762>>> class EjectFlag(Flag, boundary=EJECT):763...     RED = auto()764...     GREEN = auto()765...     BLUE = auto()766>>> EjectFlag(2**2 + 2**4)76720768```769770#### `KEEP`771772Выходящие за пределы диапазона значения сохраняются, и членство в *Flag* сохраняется. Это значение по умолчанию для [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag):773774```python775>>> from enum import Flag, KEEP, auto776>>> class KeepFlag(Flag, boundary=KEEP):777...     RED = auto()778...     GREEN = auto()779...     BLUE = auto()780>>> KeepFlag(2**2 + 2**4)781<KeepFlag.BLUE|16: 20>782```783784Новое в версии 3.11.785786---787788### Поддерживаемые `__dunder__` имена789790`__members__` представляет собой упорядоченное отображение только для чтения элементов `member_name`:`member`. Оно доступно только на уровне класса.791792[`__new__()`](https://python-all.ru/3.11/reference/datamodel.html#object.__new__), если указан, должен создавать и возвращать элементы перечисления; также рекомендуется соответствующим образом установить `_value_` элемента. После создания всех элементов он больше не используется.793794### Поддерживаемые `_sunder_` имена795796- [`_name_`](https://python-all.ru/3.11/library/enum.html#enum.Enum._name_) – имя члена797- [`_value_`](https://python-all.ru/3.11/library/enum.html#enum.Enum._value_) – значение члена; может быть задано в `__new__`798- [`_missing_()`](https://python-all.ru/3.11/library/enum.html#enum.Enum._missing_) – функция поиска, используемая, когда значение не найдено; может быть переопределена799- [`_ignore_`](https://python-all.ru/3.11/library/enum.html#enum.Enum._ignore_) – список имен, представленный в виде [`list`](https://python-all.ru/3.11/library/stdtypes.html#list) или [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), которые не будут преобразованы в члены и будут удалены из итогового класса800- [`_order_`](https://python-all.ru/3.11/library/enum.html#enum.Enum._order_) – больше не используется, сохранено для обратной совместимости (атрибут класса, удаляется при создании класса)801- [`_generate_next_value_()`](https://python-all.ru/3.11/library/enum.html#enum.Enum._generate_next_value_) – используется для получения подходящего значения для члена перечисления; может быть переопределен802803  > **Примечание**804  >805  > Для стандартных классов [`Enum`](https://python-all.ru/3.11/library/enum.html#enum.Enum) следующее выбираемое значение равно последнему увиденному значению, увеличенному на единицу.806  >807  > Для классов [`Flag`](https://python-all.ru/3.11/library/enum.html#enum.Flag) следующее выбираемое значение будет следующей по величине степенью двойки, независимо от последнего увиденного значения.808809Новое в версии 3.6: `_missing_`, `_order_`, `_generate_next_value_`810811Новое в версии 3.7: `_ignore_`812813---814815## Утилиты и декораторы816817#### `class enum.auto`818819*auto* можно использовать вместо значения. Если он используется, механизм *Enum* вызовет у *Enum* [`_generate_next_value_()`](https://python-all.ru/3.11/library/enum.html#enum.Enum._generate_next_value_) для получения подходящего значения. Для *Enum* и *IntEnum* подходящим значением будет последнее значение плюс один; для *Flag* и *IntFlag* это будет первая степень двойки, превышающая наибольшее значение; для *StrEnum* это будет версия имени элемента в нижнем регистре. Следует соблюдать осторожность при смешивании *auto()* с указанными вручную значениями.820821Экземпляры *auto* разрешаются только на верхнем уровне присваивания:822823- `FIRST = auto()` будет работать (auto() заменяется на `1`);824- `SECOND = auto(), -2` будет работать (auto заменяется на `2`, поэтому `2, -2` используется для создания элемента перечисления `SECOND`;825- `THREE = [auto(), -3]` *не* будет работать (`<auto instance>, -3` используется для создания элемента перечисления `THREE`)826827Изменено в версии 3.11.1: В предыдущих версиях `auto()` должен был быть единственным на строке присваивания, чтобы работать правильно.828829`_generate_next_value_` можно переопределить, чтобы настроить значения, используемые *auto*.830831> **Примечание**832>833> в версии 3.13 `_generate_next_value_` по умолчанию всегда будет возвращать наибольшее значение элемента, увеличенное на 1, и будет выдавать ошибку, если какой-либо элемент имеет несовместимый тип.834835#### `@enum.property`836837Декоратор, похожий на встроенный *property*, но специально для перечислений. Он позволяет атрибутам элементов иметь те же имена, что и сами элементы.838839> **Примечание**840>841> декоратор *property* и элемент должны быть определены в разных классах; например, атрибуты *value* и *name* определены в классе *Enum*, а подклассы *Enum* могут определять элементы с именами `value` и `name`.842843Новое в версии 3.11.844845#### `@enum.unique`846847Декоратор [`class`](https://python-all.ru/3.11/reference/compound_stmts.html#class), специально предназначенный для перечислений. Он просматривает `__members__` перечисления, собирая все найденные псевдонимы; если какие-либо найдены, вызывается [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError) с подробностями:848849```python850>>> from enum import Enum, unique851>>> @unique852... class Mistake(Enum):853...     ONE = 1854...     TWO = 2855...     THREE = 3856...     FOUR = 3857...858Traceback (most recent call last):859...860ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE861```862863#### `@enum.verify`864865Декоратор [`class`](https://python-all.ru/3.11/reference/compound_stmts.html#class), специально предназначенный для перечислений. Элементы из [`EnumCheck`](https://python-all.ru/3.11/library/enum.html#enum.EnumCheck) используются для указания, какие ограничения должны проверяться в декорированном перечислении.866867Новое в версии 3.11.868869#### `@enum.member`870871Декоратор для использования в перечислениях: его цель станет элементом.872873Новое в версии 3.11.874875#### `@enum.nonmember`876877Декоратор для использования в перечислениях: его цель не станет элементом.878879Новое в версии 3.11.880881#### `@enum.global_enum`882883Декоратор, изменяющий [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.11/library/functions.html#repr) перечисления, чтобы показывать его элементы как принадлежащие модулю, а не классу. Должен использоваться только когда элементы перечисления экспортируются в глобальное пространство имён модуля (см. пример [`re.RegexFlag`](https://python-all.ru/3.11/library/re.html#re.RegexFlag)).884885Новое в версии 3.11.886887#### `enum.show_flag_values(value)`888889Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся в *значении* флага.890891Новое в версии 3.11.892893---894895## Примечания896897[`IntEnum`](https://python-all.ru/3.11/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.11/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.11/library/enum.html#enum.IntFlag)898899> Эти три типа перечислений предназначены для прямой замены существующих целочисленных и строковых значений; поэтому у них есть дополнительные ограничения:900>901> - `__str__` использует значение, а не имя элемента перечисления902> - `__format__`, поскольку он использует `__str__`, также будет использовать значение элемента перечисления, а не его имя903>904> Если эти ограничения не нужны или нежелательны, можно либо создать свой собственный базовый класс, смешав в нём типы `int` или `str`:905>906> ```python907> >>> from enum import Enum908> >>> class MyIntEnum(int, Enum):909> ...     pass910> ```911>912> или можно переназначить соответствующее [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) и т.д. в своём перечислении:913>914> ```python915> >>> from enum import Enum, IntEnum916> >>> class MyIntEnum(IntEnum):917> ...     __str__ = Enum.__str__918> ```919