enum.md
1> **Источник:** https://python-all.ru/3.6/library/enum.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 8.13. [`enum`](https://python-all.ru/3.6/library/enum.html#module-enum) – Поддержка перечислений89Новое в версии 3.4.1011**Исходный код:** [Lib/enum.py](https://python-all.ru/src/3.6/Lib/enum.py)1213---1415Перечисление – это набор символических имён (членов), привязанных к уникальным постоянным значениям. Внутри перечисления члены можно сравнивать по идентичности, а само перечисление можно перебирать.1617## 8.13.1. Содержание модуля1819Этот модуль определяет четыре класса перечислений, которые можно использовать для определения уникальных наборов имён и значений: [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum), [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) и [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag). Также он определяет один декоратор [`unique()`](https://python-all.ru/3.6/library/enum.html#enum.unique) и один вспомогательный класс [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto).2021#### `class enum.Enum`2223Базовый класс для создания перечислимых констант. См. раздел [Функциональный API](https://python-all.ru/3.6/library/enum.html#functional-api) для альтернативного синтаксиса создания.2425#### `class enum.IntEnum`2627Базовый класс для создания перечислимых констант, которые также являются подклассами [`int`](https://python-all.ru/3.6/library/functions.html#int).2829#### `class enum.IntFlag`3031Базовый класс для создания перечислимых констант, которые можно комбинировать с помощью побитовых операторов, не теряя принадлежности к [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag). Члены [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) также являются подклассами [`int`](https://python-all.ru/3.6/library/functions.html#int).3233#### `class enum.Flag`3435Базовый класс для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag).3637#### `enum.unique()`3839Декоратор класса перечисления, который гарантирует, что каждому значению соответствует только одно имя.4041#### `class enum.auto`4243Экземпляры заменяются соответствующим значением для членов перечисления.4445Новое в версии 3.6: `Flag`, `IntFlag`, `auto`4647## 8.13.2. Создание перечисления4849Перечисления создаются с использованием синтаксиса [`class`](https://python-all.ru/3.6/reference/compound_stmts.html#class), что делает их легко читаемыми и удобными для записи. Альтернативный метод создания описан в [Функциональный API](https://python-all.ru/3.6/library/enum.html#functional-api). Чтобы определить перечисление, создайте подкласс [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) следующим образом:5051```python52>>> from enum import Enum53>>> class Color(Enum):54... RED = 155... GREEN = 256... BLUE = 357...58```5960> **Примечание**61>62> Значения членов Enum63>64> Значения членов могут быть любыми: [`int`](https://python-all.ru/3.6/library/functions.html#int), [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и т.д. Если точное значение неважно, можно использовать экземпляры [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto), и подходящее значение будет выбрано автоматически. Следует соблюдать осторожность при смешивании [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto) с другими значениями.6566> **Примечание**67>68> Терминология69>70> - Класс `Color` является *перечислением* (или *enum*)71> - Атрибуты `Color.RED`, `Color.GREEN` и т.д. являются *членами перечисления* (или *членами перечисления*) и по сути являются константами.72> - Члены перечисления имеют *имена* и *значения* (имя `Color.RED` – `RED`, значение `Color.BLUE` – `3` и т.д.)7374> **Примечание**75>76> Хотя для создания перечислений мы используем синтаксис [`class`](https://python-all.ru/3.6/reference/compound_stmts.html#class), перечисления не являются обычными классами Python. Подробнее см. [Чем отличаются перечисления?](https://python-all.ru/3.6/library/enum.html#how-are-enums-different).7778Члены перечисления имеют удобочитаемые строковые представления:7980```python81>>> print(Color.RED)82Color.RED83```8485…в то время как их `repr` содержит больше информации:8687```python88>>> print(repr(Color.RED))89<Color.RED: 1>90```9192*Тип* члена перечисления – это перечисление, к которому он принадлежит:9394```python95>>> type(Color.RED)96<enum 'Color'>97>>> isinstance(Color.GREEN, Color)98True99>>>100```101102Члены перечисления также имеют свойство, содержащее только их имя:103104```python105>>> print(Color.RED.name)106RED107```108109Перечисления поддерживают итерацию в порядке определения:110111```python112>>> class Shake(Enum):113... VANILLA = 7114... CHOCOLATE = 4115... COOKIES = 9116... MINT = 3117...118>>> for shake in Shake:119... print(shake)120...121Shake.VANILLA122Shake.CHOCOLATE123Shake.COOKIES124Shake.MINT125```126127Члены перечисления хешируемы, поэтому их можно использовать в словарях и множествах:128129```python130>>> apples = {}131>>> apples[Color.RED] = 'red delicious'132>>> apples[Color.GREEN] = 'granny smith'133>>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}134True135```136137## 8.13.3. Программный доступ к членам перечисления и их атрибутам138139Иногда бывает полезно обращаться к членам перечисления программно (например, в ситуациях, когда `Color.RED` не подходит, поскольку точный цвет неизвестен на момент написания программы). `Enum` предоставляет такой доступ:140141```python142>>> Color(1)143<Color.RED: 1>144>>> Color(3)145<Color.BLUE: 3>146```147148Если требуется обратиться к членам перечисления по *имени*, используйте доступ по ключу:149150```python151>>> Color['RED']152<Color.RED: 1>153>>> Color['GREEN']154<Color.GREEN: 2>155```156157Если есть член перечисления и требуется его `name` или `value`:158159```python160>>> member = Color.RED161>>> member.name162'RED'163>>> member.value1641165```166167## 8.13.4. Дублирование членов и значений перечисления168169Наличие двух членов перечисления с одинаковым именем недопустимо:170171```python172>>> class Shape(Enum):173... SQUARE = 2174... SQUARE = 3175...176Traceback (most recent call last):177...178TypeError: Attempted to reuse key: 'SQUARE'179```180181Однако двум членам перечисления разрешено иметь одинаковое значение. Если два члена A и B имеют одинаковое значение (и A определён первым), то B является псевдонимом A. Поиск по значению A и B вернёт A. Поиск по имени B также вернёт A:182183```python184>>> class Shape(Enum):185... SQUARE = 2186... DIAMOND = 1187... CIRCLE = 3188... ALIAS_FOR_SQUARE = 2189...190>>> Shape.SQUARE191<Shape.SQUARE: 2>192>>> Shape.ALIAS_FOR_SQUARE193<Shape.SQUARE: 2>194>>> Shape(2)195<Shape.SQUARE: 2>196```197198> **Примечание**199>200> Попытка создать член с тем же именем, что и уже определённый атрибут (другой член, метод и т.д.), или попытка создать атрибут с тем же именем, что и член, не допускается.201202## 8.13.5. Обеспечение уникальности значений перечисления203204По умолчанию перечисления допускают несколько имён в качестве псевдонимов для одного и того же значения. Если такое поведение нежелательно, можно использовать следующий декоратор, чтобы гарантировать, что каждое значение используется в перечислении только один раз:205206#### `@enum.unique`207208Декоратор [`class`](https://python-all.ru/3.6/reference/compound_stmts.html#class), предназначенный специально для перечислений. Он просматривает `__members__` перечисления, собирая все найденные псевдонимы; если таковые обнаружены, возбуждается [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError) с подробностями.209210```python211>>> from enum import Enum, unique212>>> @unique213... class Mistake(Enum):214... ONE = 1215... TWO = 2216... THREE = 3217... FOUR = 3218...219Traceback (most recent call last):220...221ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE222```223224## 8.13.6. Использование автоматических значений225226Если точное значение неважно, можно использовать [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto):227228```python229>>> from enum import Enum, auto230>>> class Color(Enum):231... RED = auto()232... BLUE = auto()233... GREEN = auto()234...235>>> list(Color)236[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]237```238239Значения выбираются с помощью `_generate_next_value_()`, который можно переопределить:240241```python242>>> class AutoName(Enum):243... def _generate_next_value_(name, start, count, last_values):244... return name245...246>>> class Ordinal(AutoName):247... NORTH = auto()248... SOUTH = auto()249... EAST = auto()250... WEST = auto()251...252>>> list(Ordinal)253[<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]254```255256> **Примечание**257>258> Цель методов по умолчанию `_generate_next_value_()` – предоставить следующий [`int`](https://python-all.ru/3.6/library/functions.html#int) в последовательности с последним указанным [`int`](https://python-all.ru/3.6/library/functions.html#int), но то, как это делается, является деталью реализации и может измениться.259260## 8.13.7. Итерация261262Перебор членов перечисления не включает псевдонимы:263264```python265>>> list(Shape)266[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]267```268269Специальный атрибут `__members__` – это упорядоченный словарь, сопоставляющий имена с элементами. Он включает все имена, определённые в перечислении, включая псевдонимы:270271```python272>>> for name, member in Shape.__members__.items():273... name, member274...275('SQUARE', <Shape.SQUARE: 2>)276('DIAMOND', <Shape.DIAMOND: 1>)277('CIRCLE', <Shape.CIRCLE: 3>)278('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)279```280281Атрибут `__members__` можно использовать для детального программного доступа к членам перечисления. Например, для поиска всех псевдонимов:282283```python284>>> [name for name, member in Shape.__members__.items() if member.name != name]285['ALIAS_FOR_SQUARE']286```287288## 8.13.8. Сравнения289290Члены перечисления сравниваются по идентичности:291292```python293>>> Color.RED is Color.RED294True295>>> Color.RED is Color.BLUE296False297>>> Color.RED is not Color.BLUE298True299```300301Упорядоченные сравнения между значениями перечисления *не* поддерживаются. Члены перечисления – не целые числа (но см. [IntEnum](https://python-all.ru/3.6/library/enum.html#intenum) ниже):302303```python304>>> Color.RED < Color.BLUE305Traceback (most recent call last):306 File "<stdin>", line 1, in <module>307TypeError: '<' not supported between instances of 'Color' and 'Color'308```309310Однако сравнения на равенство определены:311312```python313>>> Color.BLUE == Color.RED314False315>>> Color.BLUE != Color.RED316True317>>> Color.BLUE == Color.BLUE318True319```320321Сравнения со значениями, не являющимися перечислениями, всегда дают результат «не равно» (опять же, [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) был явно спроектирован для другого поведения, см. ниже):322323```python324>>> Color.BLUE == 2325False326```327328## 8.13.9. Допустимые члены и атрибуты перечислений329330В примерах выше для значений перечислений используются целые числа. Использование целых чисел – это кратко и удобно (и предусмотрено по умолчанию [функциональным API](https://python-all.ru/3.6/library/enum.html#functional-api)), но не является строгим требованием. В подавляющем большинстве случаев не важно, каково фактическое значение элемента перечисления. Но если значение *является* важным, перечисления могут иметь произвольные значения.331332Перечисления – это классы Python и могут иметь обычные методы и специальные методы. Если есть такое перечисление:333334```python335>>> class Mood(Enum):336... FUNKY = 1337... HAPPY = 3338...339... def describe(self):340... # self – это член перечисления341... return self.name, self.value342...343... def __str__(self):344... return 'my custom str! {0}'.format(self.value)345...346... @classmethod347... def favorite_mood(cls):348... # cls здесь – это перечисление349... return cls.HAPPY350...351```352353Тогда:354355```python356>>> Mood.favorite_mood()357<Mood.HAPPY: 3>358>>> Mood.HAPPY.describe()359('HAPPY', 3)360>>> str(Mood.FUNKY)361'my custom str! 1'362```363364Правила допустимости следующие: имена, начинающиеся и заканчивающиеся одним подчеркиванием, зарезервированы для перечисления и не могут использоваться; все остальные атрибуты, определенные в перечислении, становятся его членами, за исключением специальных методов ([`__str__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__str__), [`__add__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__add__) и т. д.) и дескрипторов (методы также являются дескрипторами).365366Примечание: если в перечислении определены [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__) и/или [`__init__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__init__), то все значения, переданные элементу перечисления, будут переданы в эти методы. В качестве примера см. [Planet](https://python-all.ru/3.6/library/enum.html#planet).367368## 8.13.10. Ограниченное создание подклассов перечислений369370Создание подкласса перечисления разрешено только в том случае, если перечисление не определяет никаких членов. Так делать запрещено:371372```python373>>> class MoreColor(Color):374... PINK = 17375...376Traceback (most recent call last):377...378TypeError: Cannot extend enumerations379```380381Но это разрешено:382383```python384>>> class Foo(Enum):385... def some_behavior(self):386... pass387...388>>> class Bar(Foo):389... HAPPY = 1390... SAD = 2391...392```393394Разрешение создания подклассов перечислений, определяющих члены, привело бы к нарушению некоторых важных инвариантов типов и экземпляров. С другой стороны, имеет смысл разрешить общее поведение для группы перечислений. (Пример см. в [OrderedEnum](https://python-all.ru/3.6/library/enum.html#orderedenum).)395396## 8.13.11. Сериализация (pickling)397398Перечисления могут быть упакованы и распакованы с помощью модуля pickle.399400```python401>>> from test.test_enum import Fruit402>>> from pickle import dumps, loads403>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))404True405```406407Обычные ограничения для упаковки с помощью модуля pickle применяются: перечисления, которые можно упаковать, должны быть определены на верхнем уровне модуля, так как для распаковки их нужно импортировать из этого модуля.408409> **Примечание**410>411> С протоколом pickle версии 4 можно легко упаковывать перечисления, вложенные в другие классы.412413Можно изменить способ сериализации/десериализации членов Enum, определив [`__reduce_ex__()`](https://python-all.ru/3.6/library/pickle.html#object.__reduce_ex__) в классе перечисления.414415## 8.13.12. Функциональный API416417Класс [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) является вызываемым и предоставляет следующее функциональное API:418419```python420>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')421>>> Animal422<enum 'Animal'>423>>> Animal.ANT424<Animal.ANT: 1>425>>> Animal.ANT.value4261427>>> list(Animal)428[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]429```430431Семантика этого API напоминает [`namedtuple`](https://python-all.ru/3.6/library/collections.html#collections.namedtuple). Первый аргумент вызова [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) – это имя перечисления.432433Второй аргумент – это *источник* имён членов перечисления. Это может быть строка имён, разделённых пробелами, последовательность имён, последовательность двухэлементных кортежей с парами ключ/значение или отображение (например, словарь) имён на значения. Последние два варианта позволяют присваивать произвольные значения перечислениям; остальные автоматически присваивают увеличивающиеся целые числа, начиная с 1 (используйте параметр `start` для указания другого начального значения). Возвращается новый класс, производный от [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum). Другими словами, приведённое выше присваивание `Animal` эквивалентно:434435```python436>>> class Animal(Enum):437... ANT = 1438... BEE = 2439... CAT = 3440... DOG = 4441...442```443444Причина, по которой по умолчанию используется `1`, а не `0`, заключается в том, что `0` равно `False` с точки зрения булевой логики, но все члены перечисления вычисляются в `True`.445446Сериализация перечислений, созданных с помощью функционального API, может быть сложной, поскольку для определения модуля, в котором создаётся перечисление, используются детали реализации стека вызовов (например, это не сработает, если использовать вспомогательную функцию в отдельном модуле, а также может не работать в IronPython или Jython). Решение – явно указать имя модуля следующим образом:447448```python449>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)450```451452> **Предупреждение**453>454> Если `module` не указан, и Enum не может его определить, новые члены Enum не будут поддерживать распаковку; чтобы ошибки были ближе к источнику, pickling будет отключён.455456Новый протокол pickle 4 также в некоторых обстоятельствах полагается на то, что [`__qualname__`](https://python-all.ru/3.6/library/stdtypes.html#definition.__qualname__) установлен в расположение, где pickle сможет найти класс. Например, если класс стал доступен в классе SomeData в глобальной области видимости:457458```python459>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')460```461462Полная сигнатура:463464```python465Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)466```467468**значение**469470Что новый класс Enum запишет в качестве своего имени.471472**имена**473474Члены перечисления. Это может быть строка, разделённая пробелами или запятыми (значения будут начинаться с 1, если не указано иное):475476```python477'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'478```479480или итератор имён:481482```python483['RED', 'GREEN', 'BLUE']484```485486или итератор пар (имя, значение):487488```python489[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]490```491492или отображение:493494```python495{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}496```497498**модуль**499500имя модуля, в котором находится новый класс Enum.501502**qualname**503504где в модуле находится новый класс Enum.505506**тип**507508тип, который следует примешать к новому классу Enum.509510**start**511512число, с которого начинать отсчёт, если переданы только имена.513514Изменено в версии 3.5: Добавлен параметр *start*.515516## 8.13.13. Производные перечисления517518### 8.13.13.1. IntEnum519520Первая разновидность [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) также является подклассом [`int`](https://python-all.ru/3.6/library/functions.html#int). Элементы [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) можно сравнивать с целыми числами; соответственно, целочисленные перечисления разных типов также можно сравнивать друг с другом:521522```python523>>> from enum import IntEnum524>>> class Shape(IntEnum):525... CIRCLE = 1526... SQUARE = 2527...528>>> class Request(IntEnum):529... POST = 1530... GET = 2531...532>>> Shape == 1533False534>>> Shape.CIRCLE == 1535True536>>> Shape.CIRCLE == Request.POST537True538```539540Однако их по-прежнему нельзя сравнивать со стандартными перечислениями [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum):541542```python543>>> class Shape(IntEnum):544... CIRCLE = 1545... SQUARE = 2546...547>>> class Color(Enum):548... RED = 1549... GREEN = 2550...551>>> Shape.CIRCLE == Color.RED552False553```554555Значения [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) ведут себя как целые числа и в других ожидаемых аспектах:556557```python558>>> int(Shape.CIRCLE)5591560>>> ['a', 'b', 'c'][Shape.CIRCLE]561'b'562>>> [i for i in range(Shape.SQUARE)]563[0, 1]564```565566### 8.13.13.2. IntFlag567568Следующая вариация [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), а именно [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag), также основана на [`int`](https://python-all.ru/3.6/library/functions.html#int). Разница в том, что члены [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) можно объединять с помощью побитовых операторов (&, |, ^, ~), и результат всё ещё остаётся членом [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag). Однако, как следует из названия, члены [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) также являются подклассами [`int`](https://python-all.ru/3.6/library/functions.html#int) и могут использоваться везде, где используется [`int`](https://python-all.ru/3.6/library/functions.html#int). Любая операция над членом [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag), кроме побитовых операций, приведёт к потере его принадлежности к [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag).569570Новое в версии 3.6.571572Пример класса [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag):573574```python575>>> from enum import IntFlag576>>> class Perm(IntFlag):577... R = 4578... W = 2579... X = 1580...581>>> Perm.R | Perm.W582<Perm.R|W: 6>583>>> Perm.R + Perm.W5846585>>> RW = Perm.R | Perm.W586>>> Perm.R in RW587True588```589590Также можно давать имена комбинациям:591592```python593>>> class Perm(IntFlag):594... R = 4595... W = 2596... X = 1597... RWX = 7598>>> Perm.RWX599<Perm.RWX: 7>600>>> ~Perm.RWX601<Perm.-8: -8>602```603604Ещё одно важное отличие между [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) и [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) в том, что если ни один флаг не установлен (значение равно 0), то его логическое значение – [`False`](https://python-all.ru/3.6/library/constants.html#False):605606```python607>>> Perm.R & Perm.X608<Perm.0: 0>609>>> bool(Perm.R & Perm.X)610False611```612613Поскольку члены [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) также являются подклассами [`int`](https://python-all.ru/3.6/library/functions.html#int), их можно объединять с ними:614615```python616>>> Perm.X | 8617<Perm.8|X: 9>618```619620### 8.13.13.3. Flag621622Последняя разновидность – [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag). Как и [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag), элементы [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) можно комбинировать с помощью побитовых операторов (&, |, ^, ~). В отличие от [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag), их нельзя комбинировать или сравнивать ни с каким другим перечислением [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag), а также с [`int`](https://python-all.ru/3.6/library/functions.html#int). Хотя можно задавать значения напрямую, рекомендуется использовать [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto) в качестве значения и позволить [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) выбрать подходящее значение.623624Новое в версии 3.6.625626Как и в случае с [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag), если комбинация элементов [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) не содержит установленных флагов, логическое значение равно [`False`](https://python-all.ru/3.6/library/constants.html#False):627628```python629>>> from enum import Flag, auto630>>> class Color(Flag):631... RED = auto()632... BLUE = auto()633... GREEN = auto()634...635>>> Color.RED & Color.GREEN636<Color.0: 0>637>>> bool(Color.RED & Color.GREEN)638False639```640641Отдельные флаги должны иметь значения, являющиеся степенями двойки (1, 2, 4, 8, …), в то время как комбинации флагов – нет:642643```python644>>> class Color(Flag):645... RED = auto()646... BLUE = auto()647... GREEN = auto()648... WHITE = RED | BLUE | GREEN649...650>>> Color.WHITE651<Color.WHITE: 7>652```653654Присвоение имени условию «флаги не установлены» не меняет его логическое значение:655656```python657>>> class Color(Flag):658... BLACK = 0659... RED = auto()660... BLUE = auto()661... GREEN = auto()662...663>>> Color.BLACK664<Color.BLACK: 0>665>>> bool(Color.BLACK)666False667```668669> **Примечание**670>671> Для большинства нового кода настоятельно рекомендуются [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) и [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag), поскольку [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) и [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) нарушают некоторые семантические обещания перечисления (будучи сравнимыми с целыми числами, а значит, по транзитивности, и с другими не связанными перечислениями). [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) и [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) следует использовать только в тех случаях, когда [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) и [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) не подходят; например, при замене целочисленных констант на перечисления или для взаимодействия с другими системами.672673### 8.13.13.4. Прочие674675Хотя [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) является частью модуля [`enum`](https://python-all.ru/3.6/library/enum.html#module-enum), его очень просто реализовать самостоятельно:676677```python678class IntEnum(int, Enum):679 pass680```681682Это показывает, как можно определить подобные производные перечисления; например, `StrEnum`, в который примешивается [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) вместо [`int`](https://python-all.ru/3.6/library/functions.html#int).683684Некоторые правила:6856861. При создании подкласса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) типы-примеси должны располагаться перед самим [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) в последовательности базовых классов, как в [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) примере выше.6872. Хотя [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) может содержать элементы любого типа, как только к нему примешивается дополнительный тип, все элементы должны иметь значения этого типа, например [`int`](https://python-all.ru/3.6/library/functions.html#int) выше. Это ограничение не распространяется на примеси, которые только добавляют методы и не указывают другой тип данных, такие как [`int`](https://python-all.ru/3.6/library/functions.html#int) или [`str`](https://python-all.ru/3.6/library/stdtypes.html#str).6883. При примешивании другого типа данных атрибут `value` *отличается* от самого члена перечисления, хотя он эквивалентен и будет равным при сравнении.6894. Форматирование в стиле %: *%s* и *%r* вызывают методы [`__str__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__str__) и [`__repr__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__repr__) класса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) соответственно; другие коды (например, *%i* или *%h* для IntEnum) обрабатывают член перечисления как его примешанный тип.6905. [Форматированные строковые литералы](https://python-all.ru/3.6/reference/lexical_analysis.html#f-strings), [`str.format()`](https://python-all.ru/3.6/library/stdtypes.html#str.format), и [`format()`](https://python-all.ru/3.6/library/functions.html#format) будут использовать [`__format__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__format__) примешанного типа. Если требуется [`str()`](https://python-all.ru/3.6/library/stdtypes.html#str) или [`repr()`](https://python-all.ru/3.6/library/functions.html#repr) класса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), используйте коды форматирования *!s* или *!r*.691692## 8.13.14. Интересные примеры693694Хотя ожидается, что [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum), [`IntFlag`](https://python-all.ru/3.6/library/enum.html#enum.IntFlag) и [`Flag`](https://python-all.ru/3.6/library/enum.html#enum.Flag) покрывают большинство случаев использования, они не могут охватить их все. Ниже приведены рецепты для некоторых других типов перечислений, которые можно использовать напрямую или как примеры для создания собственных.695696### 8.13.14.1. Пропуск значений697698Во многих случаях использования неважно, каково фактическое значение элемента перечисления. Есть несколько способов определить такой простой тип перечисления:699700- использовать экземпляры [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto) в качестве значения701- использовать экземпляры [`object`](https://python-all.ru/3.6/library/functions.html#object) в качестве значения702- использовать описательную строку в качестве значения703- использовать кортеж в качестве значения и собственный [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__) для замены кортежа на значение [`int`](https://python-all.ru/3.6/library/functions.html#int)704705Использование любого из этих методов показывает пользователю, что эти значения не важны, а также позволяет добавлять, удалять или переупорядочивать члены без необходимости перенумерации остальных членов.706707Какой бы метод ни был выбран, следует предоставить [`repr()`](https://python-all.ru/3.6/library/functions.html#repr), который также скрывает (неважное) значение:708709```python710>>> class NoValue(Enum):711... def __repr__(self):712... return '<%s.%s>' % (self.__class__.__name__, self.name)713...714```715716#### 8.13.14.1.1. Использование [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto)717718Использование [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto) будет выглядеть так:719720```python721>>> class Color(NoValue):722... RED = auto()723... BLUE = auto()724... GREEN = auto()725...726>>> Color.GREEN727<Color.GREEN>728```729730#### 8.13.14.1.2. Использование [`object`](https://python-all.ru/3.6/library/functions.html#object)731732Использование [`object`](https://python-all.ru/3.6/library/functions.html#object) будет выглядеть так:733734```python735>>> class Color(NoValue):736... RED = object()737... GREEN = object()738... BLUE = object()739...740>>> Color.GREEN741<Color.GREEN>742```743744#### 8.13.14.1.3. Использование описательной строки745746Использование строки в качестве значения будет выглядеть так:747748```python749>>> class Color(NoValue):750... RED = 'stop'751... GREEN = 'go'752... BLUE = 'too fast!'753...754>>> Color.GREEN755<Color.GREEN>756>>> Color.GREEN.value757'go'758```759760#### 8.13.14.1.4. Использование настраиваемого [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__)761762Использование автонумерующего [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__) будет выглядеть так:763764```python765>>> class AutoNumber(NoValue):766... def __new__(cls):767... value = len(cls.__members__) + 1768... obj = object.__new__(cls)769... obj._value_ = value770... return obj771...772>>> class Color(AutoNumber):773... RED = ()774... GREEN = ()775... BLUE = ()776...777>>> Color.GREEN778<Color.GREEN>779>>> Color.GREEN.value7802781```782783> **Примечание**784>785> Метод [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__), если он определён, используется во время создания членов Enum; затем он заменяется методом [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__) класса Enum, который используется после создания класса для поиска существующих членов.786787### 8.13.14.2. OrderedEnum788789Упорядоченное перечисление, которое не основано на [`IntEnum`](https://python-all.ru/3.6/library/enum.html#enum.IntEnum) и поэтому сохраняет обычные инварианты [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) (например, несравнимость с другими перечислениями):790791```python792>>> class OrderedEnum(Enum):793... def __ge__(self, other):794... if self.__class__ is other.__class__:795... return self.value >= other.value796... return NotImplemented797... def __gt__(self, other):798... if self.__class__ is other.__class__:799... return self.value > other.value800... return NotImplemented801... def __le__(self, other):802... if self.__class__ is other.__class__:803... return self.value <= other.value804... return NotImplemented805... def __lt__(self, other):806... if self.__class__ is other.__class__:807... return self.value < other.value808... return NotImplemented809...810>>> class Grade(OrderedEnum):811... A = 5812... B = 4813... C = 3814... D = 2815... F = 1816...817>>> Grade.C < Grade.A818True819```820821### 8.13.14.3. DuplicateFreeEnum822823Вызывает ошибку, если обнаружено дублирующееся имя члена, вместо создания псевдонима:824825```python826>>> class DuplicateFreeEnum(Enum):827... def __init__(self, *args):828... cls = self.__class__829... if any(self.value == e.value for e in cls):830... a = self.name831... e = cls(self.value).name832... raise ValueError(833... "aliases not allowed in DuplicateFreeEnum: %r --> %r"834... % (a, e))835...836>>> class Color(DuplicateFreeEnum):837... RED = 1838... GREEN = 2839... BLUE = 3840... GRENE = 2841...842Traceback (most recent call last):843...844ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'845```846847> **Примечание**848>849> Это полезный пример подкласса Enum для добавления или изменения другого поведения, а также запрета псевдонимов. Если требуется только запрет псевдонимов, вместо этого можно использовать декоратор [`unique()`](https://python-all.ru/3.6/library/enum.html#enum.unique).850851### 8.13.14.4. Planet852853Если определены [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__) или [`__init__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__init__), значение члена перечисления будет передано этим методам:854855```python856>>> class Planet(Enum):857... MERCURY = (3.303e+23, 2.4397e6)858... VENUS = (4.869e+24, 6.0518e6)859... EARTH = (5.976e+24, 6.37814e6)860... MARS = (6.421e+23, 3.3972e6)861... JUPITER = (1.9e+27, 7.1492e7)862... SATURN = (5.688e+26, 6.0268e7)863... URANUS = (8.686e+25, 2.5559e7)864... NEPTUNE = (1.024e+26, 2.4746e7)865... def __init__(self, mass, radius):866... self.mass = mass # в килограммах867... self.radius = radius # в метрах868... @property869... def surface_gravity(self):870... # гравитационная постоянная (м3 кг-1 с-2)871... G = 6.67300E-11872... return G * self.mass / (self.radius * self.radius)873...874>>> Planet.EARTH.value875(5.976e+24, 6378140.0)876>>> Planet.EARTH.surface_gravity8779.802652743337129878```879880## 8.13.15. Чем отличаются перечисления?881882Перечисления имеют собственный метакласс, который влияет на многие аспекты как производных классов Enum, так и их экземпляров (членов).883884### 8.13.15.1. Классы перечислений885886Мета-класс `EnumMeta` отвечает за предоставление [`__contains__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__contains__), [`__dir__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__dir__), [`__iter__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__iter__) и других методов, которые позволяют выполнять с классом [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) действия, которые на обычном классе не сработают, например *list(Color)* или *some\_var in Color*. `EnumMeta` отвечает за обеспечение того, чтобы различные другие методы итогового класса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) были корректны (таких как [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__), [`__getnewargs__()`](https://python-all.ru/3.6/library/pickle.html#object.__getnewargs__), [`__str__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__str__) и [`__repr__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__repr__)).887888### 8.13.15.2. Элементы перечисления (также экземпляры)889890Самое интересное в членах Enum – это то, что они являются синглтонами. `EnumMeta` создаёт их все при создании самого класса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), а затем помещает на место настраиваемый [`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__), чтобы гарантировать, что новые экземпляры никогда не будут созданы, возвращая только существующие экземпляры членов.891892### 8.13.15.3. Тонкости893894#### 8.13.15.3.1. Поддерживаемые `__dunder__` имена895896`__members__` – это `OrderedDict` из `member_name`:`member` элементов. Он доступен только у класса.897898[`__new__()`](https://python-all.ru/3.6/reference/datamodel.html#object.__new__), если указан, должен создавать и возвращать элементы перечисления; также рекомендуется соответствующим образом установить `_value_` элемента. После создания всех элементов он больше не используется.899900#### 8.13.15.3.2. Поддерживаемые `_sunder_` имена901902- `_name_` – имя члена903- `_value_` – значение элемента; может быть установлено / изменено в `__new__`904- `_missing_` – функция поиска, используемая, когда значение не найдено; может быть переопределена905- `_order_` – используется в коде для Python 2/3 для обеспечения согласованности порядка элементов (атрибут класса, удаляется при создании класса)906- `_generate_next_value_` – используется [функциональным API](https://python-all.ru/3.6/library/enum.html#functional-api) и [`auto`](https://python-all.ru/3.6/library/enum.html#enum.auto) для получения подходящего значения для элемента перечисления; может быть переопределён907908Новое в версии 3.6: `_missing_`, `_order_`, `_generate_next_value_`909910Чтобы помочь синхронизировать код Python 2 и Python 3, можно указать атрибут `_order_`. Он будет проверен на соответствие фактическому порядку перечисления, и если они не совпадают, будет вызвана ошибка:911912```python913>>> class Color(Enum):914... _order_ = 'RED GREEN BLUE'915... RED = 1916... BLUE = 3917... GREEN = 2918...919Traceback (most recent call last):920...921TypeError: member order does not match _order_922```923924> **Примечание**925>926> В коде Python 2 атрибут `_order_` необходим, поскольку порядок определения теряется до того, как его можно зафиксировать.927928#### 8.13.15.3.3. `Enum` тип элемента929930Члены [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) являются экземплярами своего класса [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) и обычно доступны как `EnumClass.member`. При определённых обстоятельствах к ним также можно обращаться как `EnumClass.member.member`, но никогда не следует этого делать, так как такой поиск может завершиться неудачей или, что ещё хуже, вернуть что-то кроме искомого члена [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) (это ещё одна веская причина использовать для членов имена в верхнем регистре):931932```python933>>> class FieldTypes(Enum):934... name = 0935... value = 1936... size = 2937...938>>> FieldTypes.value.size939<FieldTypes.size: 2>940>>> FieldTypes.size.value9412942```943944Изменено в версии 3.5.945946#### 8.13.15.3.4. Булево значение `Enum` классов и элементов947948Члены [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum), смешанные с не-[`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) типами (такими как [`int`](https://python-all.ru/3.6/library/functions.html#int), [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и т.п.), вычисляются по правилам примешанного типа; в противном случае все члены вычисляются как [`True`](https://python-all.ru/3.6/library/constants.html#True). Чтобы логическое вычисление вашего собственного Enum зависело от значения члена, добавьте в свой класс следующее:949950```python951def __bool__(self):952 return bool(self.value)953```954955Классы [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) всегда вычисляются как [`True`](https://python-all.ru/3.6/library/constants.html#True).956957#### 8.13.15.3.5. `Enum` классы с методами958959Если добавить подклассу [`Enum`](https://python-all.ru/3.6/library/enum.html#enum.Enum) дополнительные методы, как в классе [Planet](https://python-all.ru/3.6/library/enum.html#planet) выше, эти методы будут видны в [`dir()`](https://python-all.ru/3.6/library/functions.html#dir) члена, но не класса:960961```python962>>> dir(Planet)963['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']964>>> dir(Planet.EARTH)965['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value']966```967968#### 8.13.15.3.6. Объединение элементов `Flag`969970Если комбинация членов Flag не имеет имени, [`repr()`](https://python-all.ru/3.6/library/functions.html#repr) будет включать все именованные флаги и все именованные комбинации флагов, присутствующие в значении:971972```python973>>> class Color(Flag):974... RED = auto()975... GREEN = auto()976... BLUE = auto()977... MAGENTA = RED | BLUE978... YELLOW = RED | GREEN979... CYAN = GREEN | BLUE980...981>>> Color(3) # именованная комбинация982<Color.YELLOW: 3>983>>> Color(7) # не именованная комбинация984<Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>985```986