`!enum` --- Support for enumerations

Source code: Lib/enum.py

An enumeration:

• is a set of symbolic names (members) bound to unique values
• can be iterated over to return its canonical (i.e. non-alias) members in definition order
• uses call syntax to return members by value
• uses index syntax to return members by name

Enumerations are created either by using class syntax, or by using function-call syntax:

>>> from enum import Enum

>>> # class syntax
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

>>> # functional syntax
>>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])

Even though we can use class syntax to create Enums, Enums are not normal Python classes. See How are Enums different? <enum-class-differences> for more details.

[!NOTE] Nomenclature

• The class !Color is an enumeration (or enum)
• The attributes !Color.RED, !Color.GREEN, etc., are enumeration members (or members) and are functionally constants.
• The enum members have names and values (the name of !Color.RED is RED, the value of !Color.BLUE is 3, etc.)

Module contents

EnumType

The type for Enum and its subclasses.

Enum

Base class for creating enumerated constants.

IntEnum

Base class for creating enumerated constants that are also subclasses of int. (Notes)

StrEnum

Base class for creating enumerated constants that are also subclasses of str. (Notes)

Flag

Base class for creating enumerated constants that can be combined using the bitwise operations without losing their Flag membership.

IntFlag

Base class for creating enumerated constants that can be combined using the bitwise operators without losing their IntFlag membership. IntFlag members are also subclasses of int. (Notes)

ReprEnum

Used by IntEnum, StrEnum, and IntFlag to keep the str() <str> of the mixed-in type.

EnumCheck

An enumeration with the values CONTINUOUS, NAMED_FLAGS, and UNIQUE, for use with verify to ensure various constraints are met by a given enumeration.

FlagBoundary

An enumeration with the values STRICT, CONFORM, EJECT, and KEEP which allows for more fine-grained control over how invalid values are dealt with in an enumeration.

EnumDict

A subclass of dict for use when subclassing EnumType.

auto

Instances are replaced with an appropriate value for Enum members. StrEnum defaults to the lower-cased version of the member name, while other Enums default to 1 and increase from there.

~enum.property

Allows Enum members to have attributes without conflicting with member names. The value and name attributes are implemented this way.

unique

Enum class decorator that ensures only one name is bound to any one value.

verify

Enum class decorator that checks user-selectable constraints on an enumeration.

member

Make obj a member. Can be used as a decorator.

nonmember

Do not make obj a member. Can be used as a decorator.

global_enum

Modify the str() <str> and repr of an enum to show its members as belonging to the module instead of its class, and export the enum members to the global namespace.

show_flag_values

Return a list of all power-of-two integers contained in a flag.

enum.bin

Like built-in bin, except negative values are represented in two's complement, and the leading bit always indicates sign (0 implies positive, 1 implies negative).

Data types

>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True

>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__', '_generate_next_value_', '_missing_']

>>> Color['BLUE']
<Color.BLUE: 3>

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]

>>> len(Color)
3

>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

>>> Color.BLUE.name
'BLUE'

>>> Color.RED.value
1

>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
   ['RED', 'BLUE', 'GREEN']
   ['RED', 'GREEN', 'BLUE']

>>> from enum import Enum
>>> import datetime as dt
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @classmethod
...     def today(cls):
...         print(f'today is {cls(dt.date.today().isoweekday()).name}')
...
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', '_add_alias_', '_add_value_alias_', '_generate_next_value_', '_missing_', 'name', 'today', 'value']

>>> from enum import auto, Enum
>>> class PowersOfThree(Enum):

>>> from enum import auto, StrEnum
>>> class Build(StrEnum):
...     DEBUG = auto()
...     OPTIMIZED = auto()
...     @classmethod
...     def _missing_(cls, value):
...         value = value.lower()
...         for member in cls:
...             if member.value == value:
...                 return member
...         return None
...
>>> Build.DEBUG.value
'debug'
>>> Build('deBUG')
<Build.DEBUG: 'debug'>

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __repr__(self):
...         cls_name = self.__class__.__name__
...         return f'{cls_name}.{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __str__(self):
...         return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')

>>> from enum import auto, Enum
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __format__(self, spec):
...         return f'{self.name}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

>>> Color.RED._add_alias_("ERROR")
>>> Color.ERROR
<Color.RED: 1>

>>> Color.RED._add_value_alias_(42)
>>> Color(42)
<Color.RED: 1>

>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> purple = Color.RED | Color.BLUE
>>> white = Color.RED | Color.GREEN | Color.BLUE
>>> Color.GREEN in purple
False
>>> Color.GREEN in white
True
>>> purple in white
True
>>> white in purple
False

>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]

>>> len(Color.GREEN)
1
>>> len(white)
3

>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False

>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>

>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>

>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>

>>> ~white
<Color: 0>
>>> ~purple
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>

>>> Color.RED + 2
3

>>> Color(0)
<Color: 0>

>>> from enum import Enum, verify, UNIQUE
>>> @verify(UNIQUE)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     CRIMSON = 1
Traceback (most recent call last):
...
ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED

>>> from enum import Enum, verify, CONTINUOUS
>>> @verify(CONTINUOUS)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 5
Traceback (most recent call last):
...
ValueError: invalid enum 'Color': missing values 3, 4

>>> from enum import Flag, verify, NAMED_FLAGS
>>> @verify(NAMED_FLAGS)
... class Color(Flag):
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     WHITE = 15
...     NEON = 31
Traceback (most recent call last):
...
ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]

>>> from enum import Flag, STRICT, auto
>>> class StrictFlag(Flag, boundary=STRICT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> StrictFlag(2**2 + 2**4)
Traceback (most recent call last):
...
ValueError: <flag 'StrictFlag'> invalid value 20
    given 0b0 10100
  allowed 0b0 00111

>>> from enum import Flag, CONFORM, auto
>>> class ConformFlag(Flag, boundary=CONFORM):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> ConformFlag(2**2 + 2**4)
<ConformFlag.BLUE: 4>

>>> from enum import Flag, KEEP, auto
>>> class KeepFlag(Flag, boundary=KEEP):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> KeepFlag(2**2 + 2**4)
<KeepFlag.BLUE|16: 20>

Supported __dunder__ names

~EnumType.__members__ is a read-only ordered mapping of member_name:member items. It is only available on the class.

~Enum.__new__, if specified, must create and return the enum members; it is also a very good idea to set the member's ~Enum._value_ appropriately. Once all the members are created it is no longer used.

Supported _sunder_ names

• ~Enum._name_ -- name of the member
• ~Enum._value_ -- value of the member; can be set in __new__
• ~Enum._missing_ -- a lookup function used when a value is not found; may be overridden
• ~Enum._ignore_ -- a list of names, either as a list or a str, that will not be transformed into members, and will be removed from the final class
• ~Enum._order_ -- no longer used, kept for backward compatibility (class attribute, removed during class creation)
• ~Enum._generate_next_value_ -- used to get an appropriate value for an enum member; may be overridden
• ~Enum._add_alias_ -- adds a new name as an alias to an existing member.
• ~Enum._add_value_alias_ -- adds a new value as an alias to an existing member.
• While _sunder_ names are generally reserved for the further development of the Enum class and can not be used, some are explicitly allowed:
  • _repr_* (e.g. _repr_html_), as used in IPython's rich display

Utilities and decorators

>>> from enum import Enum, unique
>>> @unique
... class Mistake(Enum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...     FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE

Notes

IntEnum, StrEnum, and IntFlag

These three enum types are designed to be drop-in replacements for existing integer- and string-based values; as such, they have extra limitations:

• __str__ uses the value and not the name of the enum member
• __format__, because it uses __str__, will also use the value of the enum member instead of its name

If you do not need/want those limitations, you can either create your own base class by mixing in the int or str type yourself:

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass

or you can reassign the appropriate str, etc., in your enum:

>>> from enum import Enum, IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = Enum.__str__