Сообщить об ошибке.

Что такое перечисления enum в Python

Перечисления Enum в Python - это набор символических имен (членов), привязанных к уникальным постоянным значениям. Внутри перечисления члены могут сравниваться по идентичности, а само перечисление может повторяться.

Перечисления Enum похожи на глобальные переменные, но предлагают более полезную функцию repr(), группировку, безопасность типов и некоторые другие функции. Они наиболее полезны, когда есть переменная, которая может принимать одно из ограниченного набора значений, например, дни недели или основные цвета RGB.

И так, перечисления Enum:

  • представляет собой набор символических имен (членов), привязанных к уникальным значениям,
  • могут быть повторы, чтобы возвращать его члены в порядке определения,
  • используют синтаксис вызова (например Color(1)) для извлечения элементов по значению,
  • использует синтаксис индекса Color['RED'] для извлечения членов по имени.

Перечисления создаются либо с использованием синтаксиса класса, либо с использованием функционального синтаксиса:

from enum import Enum

# синтаксис класса
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

# функциональный синтаксис
Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])

Несмотря на то, для создания перечислений может использоваться синтаксис класса, перечисления не являются обычными классами Python.

Обратите внимание.

  • Так как перечисления используются для представления констант, то рекомендуется использовать стиль написания имен для членов перечисления - UPPER_CASE, так же этот стиль будет использоваться в примерах.

Модуль enum определяет пять классов перечислений, которые можно использовать для определения уникальных наборов имен и значений: enum.Enum, enum.IntEnum, enum.StrEnum, enum.Flag и enum.IntFlag. Он также определяет несколько декораторов и один помощник enum.auto.

enum.Enum:

Базовый класс enum.Enum предназначен для создания нумерованных констант.

enum.IntEnum:

Базовый класс enum.IntEnum предназначен для создания перечисляемых констант, которые являются подклассами int.

StrEnum:

Базовый класс для создания перечислимых констант, которые также являются подклассами str. (Добавлен в Python 3.11)

enum.IntFlag:

Базовый класс enum.IntFlag предназначен для создания перечисляемых констант, которые можно комбинировать с помощью побитовых операторов без потери членства в enum.IntFlag. Члены базового класса enum.IntFlag также являются подклассами int.

enum.Flag:

Базовый класс enum.Flag предназначен для создания пронумерованных констант, которые можно комбинировать с помощью побитовых операций без потери их принадлежности к базовому классу enum.Flag.

enum.EnumCheck:

Класс enum.EnumCheck - это перечисление со значениями CONTINUOUS, NAMED_FLAGS и UNIQUE для использования с декоратором @enum.verify(), чтобы гарантировать, что данное перечисление соответствует различным ограничениям. (Добавлен в Python 3.11)

enum.FlagBoundary:

Класс enum.FlagBoundary - это перечисление со значениями STRICT, CONFORM, EJECT и KEEP, которое позволяет более детально контролировать, как обрабатываются недопустимые значения в перечислении. (Добавлен в Python 3.11)

enum.auto:

Класс enum.auto заменяет экземпляры членов enum.Enum соответствующим значением. По умолчанию начальное значение начинается с 1.

@enum.unique():

Декоратор @enum.unique() обеспечивает привязку только одного имени к любому значению.

@enum.property():

Декоратор @enum.property() аналогичный встроенному @property(), но специально для перечислений. Позволяет членам Enum иметь атрибуты, не конфликтуя с именами членов перечислений. (Добавлен в Python 3.11)

Обратите внимание, что атрибуты и члены перечисления должны быть определены в отдельных классах. Например, атрибуты value и name определены в классе Enum, а подклассы Enum могут определять элементы с именами value и name.

@enum.verify():

Декоратор @enum.verify() проверяет выбираемые пользователем ограничения перечисления. (Добавлен в Python 3.11)

Новое в Python 3.6: добавлены enum.Flag, enum.IntFlag, enum.auto

Новое в Python 3.11: добавлены enum.StrEnum, enum.EnumCheck, enum.FlagBoundary, @enum.verify(), @enum.property().

Заметки по enum.IntEnum, enum.StrEnum и enum.IntFlag

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

  • __str__ использует значение, а не имя члена перечисления.
  • __format__ использует __str__, следовательно будет использовать значение члена перечисления вместо его имени

Если не нужны эти ограничения, то можно либо создать свой собственный базовый класс, смешав тип int или str самостоятельно:

from enum import Enum

class MyIntEnum(int, Enum):
    pass

или можно переназначить соответствующий str() и т. д. в своем перечислении:

from enum import IntEnum

class MyIntEnum(IntEnum):
    __str__ = IntEnum.__str__

Пример использования модуля enum:

>>> from enum import Enum
>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129