enum — enumerations

Enum, IntEnum, and StrEnum member lookup and value comparison, plus auto and unique, checked on Python 3.13.12.

The enum module, added in Python 3.4, defines a set of symbolic members bound to values. Members can be looked up by value with Color(1) and by name with Color['RED']. Canonical members iterate in definition order.

Plain Enum members are not equal to their raw values. IntEnum members are also integers, and StrEnum members, added in Python 3.11, are also strings. This page does not document Flag or IntFlag in depth.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

Enum, auto, and unique

A plain Enum member compares equal only to itself, including when another enumeration defines a member with the same value. Color.RED == 1 is False. Color.RED is Color.RED is True because members are singletons. Ordered comparisons such as Color.RED < Color.BLUE raise TypeError.

enum.auto() fills in a value; for a plain Enum the values start at 1 and increase. @enum.unique raises ValueError if two names are bound to the same value. Duplicate values without unique become aliases and are skipped when iterating canonical members.

enum.Enum, enum.auto, enum.unique

class enum.Enum
enum.auto()
@enum.unique

Define members, look them up by value or name, and reject duplicated values with unique.

ParameterDescription
value / nameColor(1) returns the member whose value is 1. Color['RED'] returns the member whose name is RED.

Returns: The class call and the name index return a member. auto is replaced by a generated value when the class is created.

Raises

  • TypeError — Raised by ordered comparisons between plain Enum members, such as Color.RED < Color.BLUE on Python 3.13.12.
  • ValueError — @unique raises ValueError when two names would share one value. Color(missing) also raises ValueError.
  • KeyError — Color['missing'] raises KeyError when the name does not exist.
  • Color.RED == Other.RED is False even though both values are 1, because they belong to different Enum classes and are not integers.
python
from enum import Enum, auto, unique

class Color(Enum):
    RED = 1
    BLUE = 2

class Other(Enum):
    RED = 1

print(Color.RED == Color.RED, Color.RED is Color.RED, Color.RED == 1)
print(Color.RED == Color.BLUE, Color.RED == Other.RED)
print(Color(1) is Color.RED, Color["RED"] is Color.RED)
print(Color.RED.name, Color.RED.value)
try:
    Color.RED < Color.BLUE
except TypeError as err:
    print(type(err).__name__)

try:
    @unique
    class Dup(Enum):
        A = 1
        B = 1
except ValueError as err:
    print(type(err).__name__)

class AutoC(Enum):
    A = auto()
    B = auto()

print(AutoC.A.value, AutoC.B.value)

Expected output

True True False
False False
True True
RED 1
TypeError
ValueError
1 2

Official documentation →

IntEnum and StrEnum comparison

IntEnum members are subclasses of int and can be used where an integer is accepted. Official documentation notes that Num.THREE == 3 is True, and that an integer operation such as Num.ONE + 1 returns a plain int and loses the enumeration type. Because comparison uses the integer value, IntEnum members from different classes compare equal when their values are equal.

StrEnum, added in Python 3.11, mixes in str. Shade.RED == "red" is True. For StrEnum, auto() uses the lower-cased member name. Official notes also say that __str__ for IntEnum and StrEnum uses the value, not the member name, so print(Shade.BLUE) writes blue rather than Shade.BLUE.

enum.IntEnum, enum.StrEnum, enum.auto

class enum.IntEnum
class enum.StrEnum
enum.auto()

Compare IntEnum members with integers and StrEnum members with strings, including across different enumerations for IntEnum.

ParameterDescription
valueIntEnum values must be integers (or convertible as documented for the int mixin). StrEnum values must be strings. auto() chooses 1, 2, ... for IntEnum, and the lower-cased name for StrEnum.

Returns: Members that also behave as int or str. Arithmetic on IntEnum members returns int.

  • These mixins are designed as drop-in replacements for existing integer or string constants. If you need Enum-style __str__, official documentation shows assigning Enum.__str__ on the subclass.
python
from enum import IntEnum, StrEnum, auto

class Num(IntEnum):
    ONE = 1
    TWO = 2

class Also(IntEnum):
    UNO = 1

print(Num.ONE == 1, Num.ONE < 2, Num.ONE + 1)
print(type(Num.ONE + 1).__name__, Num.ONE == Also.UNO)

class Shade(StrEnum):
    RED = "red"
    BLUE = auto()

print(Shade.RED == "red", Shade.BLUE == "blue", Shade.BLUE)
print(list(Shade))

Expected output

True True 2
int True
True True blue
[<Shade.RED: 'red'>, <Shade.BLUE: 'blue'>]

Official documentation →