`enum.md`

1091 строк · 54.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/Lib/enum.py)1213Важно1415На этой странице содержится справочная информация по API. Обучающую информацию и обсуждение более сложных тем см. в1617- [Базовое руководство](https://python-all.ru/3.13/howto/enum.html#enum-basic-tutorial)18- [Продвинутое руководство](https://python-all.ru/3.13/howto/enum.html#enum-advanced-tutorial)19- [Кулинарная книга Enum](https://python-all.ru/3.13/howto/enum.html#enum-cookbook)2021---2223Перечисление:2425- это набор символических имён (членов), привязанных к уникальным значениям26- может быть перебрано для возврата канонических (т.е. не псевдонимов) членов в порядке определения27- использует синтаксис *вызова* для возврата членов по значению28- использует синтаксис *индексации* для возврата членов по имени2930Перечисления создаются либо с помощью синтаксиса [`class`](https://python-all.ru/3.13/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.13/reference/compound_stmts.html#class), перечисления не являются обычными классами Python. См. [Чем перечисления отличаются?](https://python-all.ru/3.13/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.13/library/enum.html#enum.EnumType)60>61> > `type` для Enum и его подклассов.62>63> [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum)64>65> > Базовый класс для создания перечисляемых констант.66>67> [`IntEnum`](https://python-all.ru/3.13/library/enum.html#enum.IntEnum)68>69> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`int`](https://python-all.ru/3.13/library/functions.html#int). ([Примечания](https://python-all.ru/3.13/library/enum.html#notes))70>71> [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum)72>73> > Базовый класс для создания перечисляемых констант, которые также являются подклассами [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). ([Примечания](https://python-all.ru/3.13/library/enum.html#notes))74>75> [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag)76>77> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag).78>79> [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag)80>81> > Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операторов без потери их принадлежности к [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag). Члены `IntFlag` также являются подклассами [`int`](https://python-all.ru/3.13/library/functions.html#int). ([Примечания](https://python-all.ru/3.13/library/enum.html#notes))82>83> [`ReprEnum`](https://python-all.ru/3.13/library/enum.html#enum.ReprEnum)84>85> > Используется [`IntEnum`](https://python-all.ru/3.13/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag) для сохранения [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) примешиваемого типа.86>87> [`EnumCheck`](https://python-all.ru/3.13/library/enum.html#enum.EnumCheck)88>89> > Перечисление со значениями `CONTINUOUS`, `NAMED_FLAGS` и `UNIQUE`, для использования с [`verify()`](https://python-all.ru/3.13/library/enum.html#enum.verify), чтобы гарантировать соблюдение различных ограничений для заданного перечисления.90>91> [`FlagBoundary`](https://python-all.ru/3.13/library/enum.html#enum.FlagBoundary)92>93> > Перечисление со значениями `STRICT`, `CONFORM`, `EJECT` и `KEEP`, которое обеспечивает более детальный контроль над обработкой недопустимых значений в перечислении.94>95> [`EnumDict`](https://python-all.ru/3.13/library/enum.html#enum.EnumDict)96>97> > Подкласс [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict) для использования при создании подкласса [`EnumType`](https://python-all.ru/3.13/library/enum.html#enum.EnumType).98>99> [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto)100>101> > Экземпляры заменяются подходящим значением для членов Enum. [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum) по умолчанию принимает значение в нижнем регистре имени члена, в то время как другие перечисления по умолчанию начинаются с 1 и увеличиваются оттуда.102>103> [`property()`](https://python-all.ru/3.13/library/enum.html#enum.property)104>105> > Позволяет членам [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum) иметь атрибуты без конфликта с именами членов. Атрибуты `value` и `name` реализованы таким образом.106>107> [`unique()`](https://python-all.ru/3.13/library/enum.html#enum.unique)108>109> > Декоратор класса перечисления, который гарантирует, что каждому значению соответствует только одно имя.110>111> [`verify()`](https://python-all.ru/3.13/library/enum.html#enum.verify)112>113> > Декоратор класса перечисления, который проверяет выбираемые пользователем ограничения для перечисления.114>115> [`member()`](https://python-all.ru/3.13/library/enum.html#enum.member)116>117> > Превращает `obj` в член. Может использоваться как декоратор.118>119> [`nonmember()`](https://python-all.ru/3.13/library/enum.html#enum.nonmember)120>121> > Не превращает `obj` в член. Может использоваться как декоратор.122>123> [`global_enum()`](https://python-all.ru/3.13/library/enum.html#enum.global_enum)124>125> > Изменяет [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.13/library/functions.html#repr) перечисления, чтобы его члены отображались как принадлежащие модулю, а не его классу, и экспортирует члены перечисления в глобальное пространство имён.126>127> [`show_flag_values()`](https://python-all.ru/3.13/library/enum.html#enum.show_flag_values)128>129> > Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся во флаге.130>131> [`enum.bin()`](https://python-all.ru/3.13/library/enum.html#enum.bin)132>133> > Как встроенная [`bin()`](https://python-all.ru/3.13/library/functions.html#bin), за исключением того, что отрицательные значения представляются в dополнительном коде, и старший бит всегда указывает знак (`0` означает положительное, `1` – отрицательное).134135Добавлено в версии 3.6: `Flag`, `IntFlag`, `auto`136137Добавлено в версии 3.11: `StrEnum`, `EnumCheck`, `ReprEnum`, `FlagBoundary`, `property`, `member`, `nonmember`, `global_enum`, `show_flag_values`138139Добавлено в версии 3.13: `EnumDict`140141---142143## Типы данных144145#### `class enum.EnumType`146147*EnumType* – это [метакласс](https://python-all.ru/3.13/glossary.html#term-metaclass) для перечислений *enum*. Есть возможность создать подкласс *EnumType* – подробнее см. в разделе [Subclassing EnumType](https://python-all.ru/3.13/howto/enum.html#enumtype-examples).148149`EnumType` отвечает за установку правильных методов `__repr__()`, `__str__()`, `__format__()` и `__reduce__()` в конечном перечислении *enum*, а также за создание членов перечисления, корректную обработку дубликатов, обеспечение итерации по классу перечисления и т.д.150151Добавлено в версии 3.11: До версии 3.11 `EnumType` назывался `EnumMeta`, который всё ещё доступен как псевдоним.152153#### `__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)`154155Этот метод вызывается двумя разными способами:156157- для поиска существующего члена:158159  > **cls:**160  >161  > Вызываемый класс перечисления.162  >163  > **value:**164  >165  > Значение для поиска.166- для использования перечисления `cls` для создания нового перечисления (только если существующее перечисление не имеет членов):167168  > **cls:**169  >170  > Вызываемый класс перечисления.171  >172  > **value:**173  >174  > Имя нового создаваемого перечисления.175  >176  > **names:**177  >178  > Имена/значения членов нового перечисления.179  >180  > **модуль:**181  >182  > Имя модуля, в котором создаётся новое перечисление.183  >184  > **qualname:**185  >186  > Фактическое расположение в модуле, где можно найти это перечисление.187  >188  > **тип:**189  >190  > Примесный тип для нового перечисления.191  >192  > **start:**193  >194  > Первое целое значение для перечисления (используется функцией [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto)).195  >196  > **boundary:**197  >198  > Как обрабатывать значения, выходящие за пределы диапазона в битовых операциях (только для [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag)).199200#### `__contains__(cls, member)`201202Возвращает `True`, если member принадлежит `cls`:203204```python205>>> some_var = Color.RED206>>> some_var in Color207True208>>> Color.RED.value in Color209True210```211212Изменено в версии 3.12: До Python 3.12 при проверке вхождения элемента, не являющегося членом Enum, вызывалось исключение `TypeError`.213214#### `__dir__(cls)`215216Возвращает `['__class__', '__doc__', '__members__', '__module__']` и имена членов в *cls*:217218```python219>>> dir(Color)220['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']221```222223#### `__getitem__(cls, name)`224225Возвращает член Enum из *cls*, соответствующий *name*, или вызывает [`KeyError`](https://python-all.ru/3.13/library/exceptions.html#KeyError):226227```python228>>> Color['BLUE']229<Color.BLUE: 3>230```231232#### `__iter__(cls)`233234Возвращает каждый член из *cls* в порядке определения:235236```python237>>> list(Color)238[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]239```240241#### `__len__(cls)`242243Возвращает количество членов в *cls*:244245```python246>>> len(Color)2473248```249250#### `__members__`251252Возвращает отображение каждого имени enum на его член, включая псевдонимы253254#### `__reversed__(cls)`255256Возвращает каждый член из *cls* в обратном порядке определения:257258```python259>>> list(reversed(Color))260[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]261```262263#### `class enum.Enum`264265*Enum* – это базовый класс для всех перечислений *enum*.266267#### `name`268269Имя, используемое для определения члена `Enum`:270271```python272>>> Color.BLUE.name273'BLUE'274```275276#### `value`277278Значение, присвоенное члену `Enum`:279280```python281>>> Color.RED.value2821283```284285Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__new__).286287> **Примечание**288>289> Значения членов Enum290>291> Значения членов могут быть любыми: [`int`](https://python-all.ru/3.13/library/functions.html#int), [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) и т. д. Если точное значение не важно, можно использовать экземпляры [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto), и подходящее значение будет выбрано автоматически. Подробнее см. `auto`.292>293> Хотя можно использовать изменяемые/нехешируемые значения, такие как [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict), [`list`](https://python-all.ru/3.13/library/stdtypes.html#list) или изменяемый [`dataclass`](https://python-all.ru/3.13/library/dataclasses.html#dataclasses.dataclass), они будут оказывать квадратичное влияние на производительность при создании по сравнению с общим количеством изменяемых/нехешируемых значений в перечислении.294295#### `_name_`296297Имя члена.298299#### `_value_`300301Значение члена; может быть задано в [`__new__()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__new__).302303#### `_order_`304305Больше не используется, сохранено для обратной совместимости. (атрибут класса, удаляется при создании класса).306307Атрибут `_order_` может быть указан, чтобы помочь синхронизировать код Python 2 и Python 3. Он будет сверяться с фактическим порядком перечисления и вызывать ошибку, если они не совпадают:308309```python310>>> class Color(Enum):311...     _order_ = 'RED GREEN BLUE'312...     RED = 1313...     BLUE = 3314...     GREEN = 2315...316Traceback (most recent call last):317...318TypeError: member order does not match _order_:319   ['RED', 'BLUE', 'GREEN']320   ['RED', 'GREEN', 'BLUE']321```322323> **Примечание**324>325> В коде Python 2 атрибут `_order_` необходим, поскольку порядок определения теряется до того, как его можно зафиксировать.326327Добавлено в версии 3.6.328329#### `_ignore_`330331`_ignore_` используется только во время создания и удаляется из перечисления после завершения создания.332333`_ignore_` – это список имён, которые не станут членами, и их имена также будут удалены из готового перечисления. См. пример [TimePeriod](https://python-all.ru/3.13/howto/enum.html#enum-time-period).334335Добавлено в версии 3.7.336337#### `__dir__(self)`338339Возвращает `['__class__', '__doc__', '__module__', 'name', 'value']` и все публичные методы, определённые в *self.\_\_class\_\_*:340341```python342>>> from enum import Enum343>>> import datetime as dt344>>> class Weekday(Enum):345...     MONDAY = 1346...     TUESDAY = 2347...     WEDNESDAY = 3348...     THURSDAY = 4349...     FRIDAY = 5350...     SATURDAY = 6351...     SUNDAY = 7352...     @classmethod353...     def today(cls):354...         print(f'today is {cls(dt.date.today().isoweekday()).name}')355...356>>> dir(Weekday.SATURDAY)357['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']358```359360#### `_generate_next_value_(name, start, count, last_values)`361362> **name:**363>364> Имя определяемого члена (например, 'RED').365>366> **start:**367>368> Начальное значение для Enum; по умолчанию 1.369>370> **count:**371>372> Количество уже определённых членов, не включая текущий.373>374> **last\_values:**375>376> Список предыдущих значений.377378Метод *staticmethod*, используемый для определения следующего значения, возвращаемого [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto).379380> **Примечание**381>382> Для стандартных классов `Enum` следующее выбираемое значение – это максимальное увиденное значение, увеличенное на единицу.383>384> Для классов [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) следующее выбираемое значение будет следующей по величине степенью двойки.385386Этот метод может быть переопределён, например:387388```python389>>> from enum import auto, Enum390>>> class PowersOfThree(Enum):391...     @staticmethod392...     def _generate_next_value_(name, start, count, last_values):393...         return 3 ** (count + 1)394...     FIRST = auto()395...     SECOND = auto()396...397>>> PowersOfThree.SECOND.value3989399```400401Добавлено в версии 3.6.402403Изменено в версии 3.13: В предыдущих версиях использовалось последнее увиденное значение вместо наибольшего.404405#### `__init__(self, *args, **kwds)`406407По умолчанию ничего не делает. Если в определении члена задано несколько значений, эти значения становятся отдельными аргументами для `__init__`; например:408409```python410>>> from enum import Enum411>>> class Weekday(Enum):412...     MONDAY = 1, 'Mon'413```414415`Weekday.__init__()` будет вызван как `Weekday.__init__(self, 1, 'Mon')`416417#### `__init_subclass__(cls, **kwds)`418419Метод класса *classmethod*, используемый для дальнейшей настройки последующих подклассов. По умолчанию ничего не делает.420421#### `_missing_(cls, value)`422423Метод класса *classmethod* для поиска значений, не найденных в *cls*. По умолчанию он ничего не делает, но может быть переопределён для реализации собственного поиска:424425```python426>>> from enum import auto, StrEnum427>>> class Build(StrEnum):428...     DEBUG = auto()429...     OPTIMIZED = auto()430...     @classmethod431...     def _missing_(cls, value):432...         value = value.lower()433...         for member in cls:434...             if member.value == value:435...                 return member436...         return None437...438>>> Build.DEBUG.value439'debug'440>>> Build('deBUG')441<Build.DEBUG: 'debug'>442```443444Добавлено в версии 3.6.445446#### `__new__(cls, *args, **kwds)`447448По умолчанию не существует. Если указан в определении класса перечисления или в примешиваемом классе (например, `int`), все значения, заданные в определении члена, будут переданы; например:449450```python451>>> from enum import Enum452>>> class MyIntEnum(int, Enum):453...     TWENTYSIX = '1a', 16454```455456приводит к вызову `int('1a', 16)` и значению `26` для члена.457458> **Примечание**459>460> При написании пользовательского `__new__` не используйте `super().__new__` – вместо этого вызывайте соответствующий `__new__`.461462#### `__repr__(self)`463464Возвращает строку, используемую для вызовов *repr()*. По умолчанию возвращает имя *Enum*, имя элемента и значение, но может быть переопределено:465466```python467>>> from enum import auto, Enum468>>> class OtherStyle(Enum):469...     ALTERNATE = auto()470...     OTHER = auto()471...     SOMETHING_ELSE = auto()472...     def __repr__(self):473...         cls_name = self.__class__.__name__474...         return f'{cls_name}.{self.name}'475...476>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"477(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')478```479480#### `__str__(self)`481482Возвращает строку, используемую для вызовов *str()*. По умолчанию возвращает имя *Enum* и имя элемента, но может быть переопределено:483484```python485>>> from enum import auto, Enum486>>> class OtherStyle(Enum):487...     ALTERNATE = auto()488...     OTHER = auto()489...     SOMETHING_ELSE = auto()490...     def __str__(self):491...         return f'{self.name}'492...493>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"494(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')495```496497#### `__format__(self)`498499Возвращает строку, используемую для вызовов *format()* и *f-строк*. По умолчанию возвращает возвращаемое значение [`__str__()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__str__), но может быть переопределено:500501```python502>>> from enum import auto, Enum503>>> class OtherStyle(Enum):504...     ALTERNATE = auto()505...     OTHER = auto()506...     SOMETHING_ELSE = auto()507...     def __format__(self, spec):508...         return f'{self.name}'509...510>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"511(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')512```513514> **Примечание**515>516> Использование [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto) с `Enum` даёт целые числа с возрастающим значением, начиная с `1`.517518Изменено в версии 3.12: Добавлена [поддержка dataclass](https://python-all.ru/3.13/howto/enum.html#enum-dataclass-support)519520#### `_add_alias_()`521522Добавляет новое имя как псевдоним существующего элемента:523524```python525>>> Color.RED._add_alias_("ERROR")526>>> Color.ERROR527<Color.RED: 1>528```529530Вызывает [`NameError`](https://python-all.ru/3.13/library/exceptions.html#NameError), если имя уже назначено другому элементу.531532Добавлено в версии 3.13.533534#### `_add_value_alias_()`535536Добавляет новое значение как псевдоним существующего элемента:537538```python539>>> Color.RED._add_value_alias_(42)540>>> Color(42)541<Color.RED: 1>542```543544Вызывает545546[`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError)547548, если значение уже связано с другим элементом.549550Пример см. в551552[MultiValueEnum](https://python-all.ru/3.13/howto/enum.html#multi-value-enum)553554.555556Добавлено в версии 3.13.557558#### `class enum.IntEnum`559560*IntEnum* – то же, что и [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum), но его элементы также являются целыми числами и могут использоваться везде, где можно использовать целое число. Если над элементом *IntEnum* выполняется какая-либо целочисленная операция, результирующее значение теряет статус перечисления.561562```python563>>> from enum import IntEnum564>>> class Number(IntEnum):565...     ONE = 1566...     TWO = 2567...     THREE = 3568...569>>> Number.THREE570<Number.THREE: 3>571>>> Number.ONE + Number.TWO5723573>>> Number.THREE + 55748575>>> Number.THREE == 3576True577```578579> **Примечание**580>581> Использование [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto) с `IntEnum` даёт целые числа с возрастающим значением, начиная с `1`.582583Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__str__) теперь `int.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__format__) уже был `int.__format__()` по той же причине.584585#### `class enum.StrEnum`586587*StrEnum* – то же, что и [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum), но его элементы также являются строками и могут использоваться почти везде, где можно использовать строку. Результат любой строковой операции, выполненной над элементом *StrEnum* или с его участием, не является частью перечисления.588589```python590>>> from enum import StrEnum, auto591>>> class Color(StrEnum):592...     RED = 'r'593...     GREEN = 'g'594...     BLUE = 'b'595...     UNKNOWN = auto()596...597>>> Color.RED598<Color.RED: 'r'>599>>> Color.UNKNOWN600<Color.UNKNOWN: 'unknown'>601>>> str(Color.UNKNOWN)602'unknown'603```604605> **Примечание**606>607> В стандартной библиотеке есть места, где проверяется точное совпадение с [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), а не с подклассом `str` (например, `type(unknown) == str` вместо `isinstance(unknown, str)`), и в таких случаях потребуется использовать `str(MyStrEnum.MY_MEMBER)`.608609> **Примечание**610>611> Использование [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto) с `StrEnum` даёт имя элемента в нижнем регистре в качестве значения.612613> **Примечание**614>615> [`__str__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__str__) – `str.__str__()`, чтобы лучше поддерживать вариант использования *замены существующих констант*. [`__format__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__format__) также `str.__format__()` по той же причине.616617Добавлено в версии 3.12.618619#### `class enum.Flag`620621`Flag` – то же, что и [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum), но его элементы поддерживают побитовые операторы `&` (*AND*), `|` (*OR*), `^` (*XOR*) и `~` (*INVERT*); результаты этих операций являются (псевдонимами) элементов перечисления.622623#### `__contains__(self, value)`624625Возвращает *True*, если значение находится в self:626627```python628>>> from enum import Flag, auto629>>> class Color(Flag):630...     RED = auto()631...     GREEN = auto()632...     BLUE = auto()633...634>>> purple = Color.RED | Color.BLUE635>>> white = Color.RED | Color.GREEN | Color.BLUE636>>> Color.GREEN in purple637False638>>> Color.GREEN in white639True640>>> purple in white641True642>>> white in purple643False644```645646#### `__iter__(self)`647648Возвращает все содержащиеся элементы, не являющиеся псевдонимами:649650```python651>>> list(Color.RED)652[<Color.RED: 1>]653>>> list(purple)654[<Color.RED: 1>, <Color.BLUE: 4>]655```656657Добавлено в версии 3.12.658659#### `__len__(self)`660661Возвращает количество элементов во флаге:662663```python664>>> len(Color.GREEN)6651666>>> len(white)6673668```669670Добавлено в версии 3.12.671672#### `__bool__(self)`673674Возвращает *True*, если в флаге есть хотя бы один элемент, иначе *False*:675676```python677>>> bool(Color.GREEN)678True679>>> bool(white)680True681>>> black = Color(0)682>>> bool(black)683False684```685686#### `__or__(self, other)`687688Возвращает текущий флаг, логически сложенный (OR) с другим:689690```python691>>> Color.RED | Color.GREEN692<Color.RED|GREEN: 3>693```694695#### `__and__(self, other)`696697Возвращает текущий флаг, логически умноженный (AND) с другим:698699```python700>>> purple & white701<Color.RED|BLUE: 5>702>>> purple & Color.GREEN703<Color: 0>704```705706#### `__xor__(self, other)`707708Возвращает текущий флаг, логически сложенный по исключающему ИЛИ (XOR) с другим:709710```python711>>> purple ^ white712<Color.GREEN: 2>713>>> purple ^ Color.GREEN714<Color.RED|GREEN|BLUE: 7>715```716717#### `__invert__(self)`718719Возвращает все флаги из *type(self)*, которых нет в *self*:720721```python722>>> ~white723<Color: 0>724>>> ~purple725<Color.GREEN: 2>726>>> ~Color.RED727<Color.GREEN|BLUE: 6>728```729730#### `_numeric_repr_()`731732Функция, используемая для форматирования оставшихся безымянных числовых значений. По умолчанию – repr значения; распространённые варианты: [`hex()`](https://python-all.ru/3.13/library/functions.html#hex) и [`oct()`](https://python-all.ru/3.13/library/functions.html#oct).733734> **Примечание**735>736> Использование [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto) с `Flag` даёт целые числа, являющиеся степенями двойки, начиная с `1`.737738Изменено в версии 3.11: *repr()* флагов с нулевым значением изменилась. Теперь это::739740```python741>>> Color(0)742<Color: 0>743```744745#### `class enum.IntFlag`746747`IntFlag` – то же, что и [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag), но его члены также являются целыми числами и могут использоваться везде, где можно использовать целое число.748749```python750>>> from enum import IntFlag, auto751>>> class Color(IntFlag):752...     RED = auto()753...     GREEN = auto()754...     BLUE = auto()755...756>>> Color.RED & 2757<Color: 0>758>>> Color.RED | 2759<Color.RED|GREEN: 3>760```761762Если к члену *IntFlag* применяется целочисленная операция, результат не будет *IntFlag*:763764```python765>>> Color.RED + 27663767```768769Если к члену *IntFlag* применяется операция [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) и:770771- результат является допустимым *IntFlag*: возвращается *IntFlag*772- результат не является допустимым *IntFlag*: результат зависит от настройки [`FlagBoundary`](https://python-all.ru/3.13/library/enum.html#enum.FlagBoundary)773774[`repr()`](https://python-all.ru/3.13/library/functions.html#repr) безымянных флагов с нулевым значением изменилось. Теперь он:775776```python777>>> Color(0)778<Color: 0>779```780781> **Примечание**782>783> Использование [`auto`](https://python-all.ru/3.13/library/enum.html#enum.auto) с `IntFlag` даёт целые числа, являющиеся степенями двойки, начиная с `1`.784785Изменено в версии 3.11: [`__str__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__str__) теперь `int.__str__()` для лучшей поддержки сценария *замены существующих констант*. [`__format__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__format__) уже было `int.__format__()` по той же причине.786787Инверсия `IntFlag` теперь возвращает положительное значение – объединение всех флагов, не входящих в заданный флаг, вместо отрицательного значения. Это соответствует существующему поведению [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag).788789#### `class enum.ReprEnum`790791`ReprEnum` использует [`repr()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__repr__) от [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum), но [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) от примешиваемого типа данных:792793- `int.__str__()` для [`IntEnum`](https://python-all.ru/3.13/library/enum.html#enum.IntEnum) и [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag)794- `str.__str__()` для [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum)795796Наследуйте от `ReprEnum`, чтобы сохранить [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) / [`format()`](https://python-all.ru/3.13/library/functions.html#format) примешиваемого типа данных вместо использования [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum)-умолчания [`str()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__str__).797798Добавлено в версии 3.12.799800#### `class enum.EnumCheck`801802*EnumCheck* содержит параметры, используемые декоратором [`verify()`](https://python-all.ru/3.13/library/enum.html#enum.verify) для проверки различных ограничений; нарушение ограничений приводит к [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).803804#### `UNIQUE`805806Гарантирует, что каждое значение имеет только одно имя:807808```python809>>> from enum import Enum, verify, UNIQUE810>>> @verify(UNIQUE)811... class Color(Enum):812...     RED = 1813...     GREEN = 2814...     BLUE = 3815...     CRIMSON = 1816Traceback (most recent call last):817...818ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED819```820821#### `CONTINUOUS`822823Убедитесь, что между членом с наименьшим значением и членом с наибольшим значением нет пропущенных значений:824825```python826>>> from enum import Enum, verify, CONTINUOUS827>>> @verify(CONTINUOUS)828... class Color(Enum):829...     RED = 1830...     GREEN = 2831...     BLUE = 5832Traceback (most recent call last):833...834ValueError: invalid enum 'Color': missing values 3, 4835```836837#### `NAMED_FLAGS`838839Убедитесь, что любые группы/маски флагов содержат только именованные флаги – это полезно, когда значения задаются явно, а не генерируются с помощью [`auto()`](https://python-all.ru/3.13/library/enum.html#enum.auto):840841```python842>>> from enum import Flag, verify, NAMED_FLAGS843>>> @verify(NAMED_FLAGS)844... class Color(Flag):845...     RED = 1846...     GREEN = 2847...     BLUE = 4848...     WHITE = 15849...     NEON = 31850Traceback (most recent call last):851...852ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]853```854855> **Примечание**856>857> CONTINUOUS и NAMED\_FLAGS предназначены для работы с членами, имеющими целочисленные значения.858859Добавлено в версии 3.12.860861#### `class enum.FlagBoundary`862863`FlagBoundary` определяет обработку значений, выходящих за пределы диапазона, в [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) и его подклассах.864865#### `STRICT`866867Значения вне диапазона приводят к возбуждению [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError). Это поведение по умолчанию для [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag):868869```python870>>> from enum import Flag, STRICT, auto871>>> class StrictFlag(Flag, boundary=STRICT):872...     RED = auto()873...     GREEN = auto()874...     BLUE = auto()875...876>>> StrictFlag(2**2 + 2**4)877Traceback (most recent call last):878...879ValueError: <flag 'StrictFlag'> invalid value 20880    given 0b0 10100881  allowed 0b0 00111882```883884#### `CONFORM`885886Значения вне диапазона очищаются от недопустимых значений, оставляя допустимое значение [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag):887888```python889>>> from enum import Flag, CONFORM, auto890>>> class ConformFlag(Flag, boundary=CONFORM):891...     RED = auto()892...     GREEN = auto()893...     BLUE = auto()894...895>>> ConformFlag(2**2 + 2**4)896<ConformFlag.BLUE: 4>897```898899#### `EJECT`900901Значения вне диапазона теряют членство в [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) и возвращаются к [`int`](https://python-all.ru/3.13/library/functions.html#int).902903```python904>>> from enum import Flag, EJECT, auto905>>> class EjectFlag(Flag, boundary=EJECT):906...     RED = auto()907...     GREEN = auto()908...     BLUE = auto()909...910>>> EjectFlag(2**2 + 2**4)91120912```913914#### `KEEP`915916Значения вне диапазона сохраняются, и членство в [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) также сохраняется. Это поведение по умолчанию для [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag):917918```python919>>> from enum import Flag, KEEP, auto920>>> class KeepFlag(Flag, boundary=KEEP):921...     RED = auto()922...     GREEN = auto()923...     BLUE = auto()924...925>>> KeepFlag(2**2 + 2**4)926<KeepFlag.BLUE|16: 20>927```928929Добавлено в версии 3.12.930931#### `class enum.EnumDict`932933*EnumDict* является подклассом [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict), который используется в качестве пространства имен для определения классов перечислений (см. [Подготовка пространства имен класса](https://python-all.ru/3.13/reference/datamodel.html#prepare)). Он предоставляется для поддержки подклассов [`EnumType`](https://python-all.ru/3.13/library/enum.html#enum.EnumType) с расширенным поведением, например, с несколькими значениями на одного члена. Его следует вызывать с именем создаваемого класса перечисления, в противном случае частные имена и внутренние классы будут обрабатываться некорректно.934935Обратите внимание, что переопределяется только интерфейс [`MutableMapping`](https://python-all.ru/3.13/library/collections.abc.html#collections.abc.MutableMapping) ([`__setitem__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__setitem__) и [`update()`](https://python-all.ru/3.13/library/stdtypes.html#dict.update)). Возможно обойти проверки с помощью других операций `dict`, например [`|=`](https://python-all.ru/3.13/reference/datamodel.html#object.__ior__).936937#### `member_names`938939Список имен членов.940941Добавлено в версии 3.13.942943---944945### Поддерживаемые `__dunder__` имена946947[`__members__`](https://python-all.ru/3.13/library/enum.html#enum.EnumType.__members__) представляет собой упорядоченное отображение только для чтения элементов `member_name`:`member`. Оно доступно только на уровне класса.948949[`__new__()`](https://python-all.ru/3.13/library/enum.html#enum.Enum.__new__), если указан, должен создавать и возвращать члены перечисления; также настоятельно рекомендуется соответствующим образом задать [`_value_`](https://python-all.ru/3.13/library/enum.html#enum.Enum._value_) элемента. После создания всех членов он больше не используется.950951### Поддерживаемые `_sunder_` имена952953- [`_name_`](https://python-all.ru/3.13/library/enum.html#enum.Enum._name_) – имя члена954- [`_value_`](https://python-all.ru/3.13/library/enum.html#enum.Enum._value_) – значение члена; может быть задано в `__new__`955- [`_missing_()`](https://python-all.ru/3.13/library/enum.html#enum.Enum._missing_) – функция поиска, используемая, когда значение не найдено; может быть переопределена956- [`_ignore_`](https://python-all.ru/3.13/library/enum.html#enum.Enum._ignore_) – список имен, представленный в виде [`list`](https://python-all.ru/3.13/library/stdtypes.html#list) или [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), которые не будут преобразованы в члены и будут удалены из итогового класса957- [`_order_`](https://python-all.ru/3.13/library/enum.html#enum.Enum._order_) – больше не используется, сохранено для обратной совместимости (атрибут класса, удаляется при создании класса)958- [`_generate_next_value_()`](https://python-all.ru/3.13/library/enum.html#enum.Enum._generate_next_value_) – используется для получения подходящего значения для члена перечисления; может быть переопределен959- [`_add_alias_()`](https://python-all.ru/3.13/library/enum.html#enum.Enum._add_alias_) – добавляет новое имя как псевдоним для существующего члена.960- [`_add_value_alias_()`](https://python-all.ru/3.13/library/enum.html#enum.Enum._add_value_alias_) – добавляет новое значение как псевдоним для существующего члена.961- Хотя имена `_sunder_` обычно зарезервированы для дальнейшего развития класса [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum) и не могут использоваться, некоторые явно разрешены:962963  - `_repr_*` (например, `_repr_html_`), как используется в [расширенном отображении IPython](https://python-all.ru/3.13/library/enum.html)964965Добавлено в версии 3.6: `_missing_`, `_order_`, `_generate_next_value_`966967Добавлено в версии 3.7: `_ignore_`968969Добавлено в версии 3.13: `_add_alias_`, `_add_value_alias_`, `_repr_*`970971---972973## Утилиты и декораторы974975#### `class enum.auto`976977*auto* можно использовать вместо значения. Если он используется, механизм *Enum* вызовет [`_generate_next_value_()`](https://python-all.ru/3.13/library/enum.html#enum.Enum._generate_next_value_) объекта [`Enum`](https://python-all.ru/3.13/library/enum.html#enum.Enum), чтобы получить подходящее значение. Для `Enum` и [`IntEnum`](https://python-all.ru/3.13/library/enum.html#enum.IntEnum) подходящим значением будет последнее значение плюс единица; для [`Flag`](https://python-all.ru/3.13/library/enum.html#enum.Flag) и [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag) – первая степень двойки, превышающая наибольшее значение; для [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum) – версия имени элемента в нижнем регистре. Следует соблюдать осторожность при смешивании *auto()* с явно заданными значениями.978979Экземпляры *auto* разрешаются только на верхнем уровне присваивания, отдельно или как часть кортежа:980981- `FIRST = auto()` будет работать (auto() заменяется на `1`);982- `SECOND = auto(), -2` будет работать (auto заменяется на `2`, поэтому `2, -2` используется для создания элемента перечисления `SECOND`;983- `THREE = [auto(), -3]` *не* будет работать (`[<auto instance>, -3]` используется для создания элемента перечисления `THREE`)984985Изменено в версии 3.11.1: В предыдущих версиях `auto()` должен был быть единственным на строке присваивания, чтобы работать правильно.986987`_generate_next_value_` можно переопределить, чтобы настроить значения, используемые *auto*.988989> **Примечание**990>991> в версии 3.13 `_generate_next_value_` по умолчанию всегда будет возвращать наибольшее значение элемента, увеличенное на 1, и будет выдавать ошибку, если какой-либо элемент имеет несовместимый тип.992993#### `@enum.property`994995Декоратор, похожий на встроенный *property*, но специально для перечислений. Он позволяет атрибутам элементов иметь те же имена, что и сами элементы.996997> **Примечание**998>999> декоратор *property* и элемент должны быть определены в разных классах; например, атрибуты *value* и *name* определены в классе *Enum*, а подклассы *Enum* могут определять элементы с именами `value` и `name`.10001001Добавлено в версии 3.12.10021003#### `@enum.unique`10041005Декоратор [`class`](https://python-all.ru/3.13/reference/compound_stmts.html#class), специально предназначенный для перечислений. Он просматривает [`__members__`](https://python-all.ru/3.13/library/enum.html#enum.EnumType.__members__) перечисления, собирая все найденные псевдонимы; если какие-либо найдены, вызывается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) с подробностями:10061007```python1008>>> from enum import Enum, unique1009>>> @unique1010... class Mistake(Enum):1011...     ONE = 11012...     TWO = 21013...     THREE = 31014...     FOUR = 31015...1016Traceback (most recent call last):1017...1018ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE1019```10201021#### `@enum.verify`10221023Декоратор [`class`](https://python-all.ru/3.13/reference/compound_stmts.html#class), специально предназначенный для перечислений. Элементы из [`EnumCheck`](https://python-all.ru/3.13/library/enum.html#enum.EnumCheck) используются для указания, какие ограничения должны проверяться в декорированном перечислении.10241025Добавлено в версии 3.12.10261027#### `@enum.member`10281029Декоратор для использования в перечислениях: его цель станет элементом.10301031Добавлено в версии 3.12.10321033#### `@enum.nonmember`10341035Декоратор для использования в перечислениях: его цель не станет элементом.10361037Добавлено в версии 3.12.10381039#### `@enum.global_enum`10401041Декоратор, изменяющий [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) и [`repr()`](https://python-all.ru/3.13/library/functions.html#repr) перечисления, чтобы показывать его элементы как принадлежащие модулю, а не классу. Должен использоваться только когда элементы перечисления экспортируются в глобальное пространство имён модуля (см. пример [`re.RegexFlag`](https://python-all.ru/3.13/library/re.html#re.RegexFlag)).10421043Добавлено в версии 3.12.10441045#### `enum.show_flag_values(value)`10461047Возвращает список всех целых чисел, являющихся степенями двойки, содержащихся в *значении* флага.10481049Добавлено в версии 3.12.10501051#### `enum.bin(num, max_bits=None)`10521053Как встроенная `bin()`, за исключением того, что отрицательные значения представляются в dополнительном коде, и старший бит всегда указывает знак (`0` означает положительное, `1` – отрицательное).10541055```python1056>>> import enum1057>>> enum.bin(10)1058'0b0 1010'1059>>> enum.bin(~10)   # ~10 is -111060'0b1 0101'1061```10621063Добавлено в версии 3.12.10641065---10661067## Примечания10681069[`IntEnum`](https://python-all.ru/3.13/library/enum.html#enum.IntEnum), [`StrEnum`](https://python-all.ru/3.13/library/enum.html#enum.StrEnum) и [`IntFlag`](https://python-all.ru/3.13/library/enum.html#enum.IntFlag)10701071> Эти три типа перечислений предназначены для прямой замены существующих целочисленных и строковых значений; поэтому у них есть дополнительные ограничения:1072>1073> - `__str__` использует значение, а не имя элемента перечисления1074> - `__format__`, поскольку он использует `__str__`, также будет использовать значение элемента перечисления, а не его имя1075>1076> Если эти ограничения не нужны или нежелательны, можно либо создать свой собственный базовый класс, смешав в нём типы `int` или `str`:1077>1078> ```python1079> >>> from enum import Enum1080> >>> class MyIntEnum(int, Enum):1081> ...     pass1082> ```1083>1084> или можно переназначить соответствующее [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) и т.д. в своём перечислении:1085>1086> ```python1087> >>> from enum import Enum, IntEnum1088> >>> class MyIntEnum(IntEnum):1089> ...     __str__ = Enum.__str__1090> ```1091