Constants With Meaning: A Practical Deep Dive into Python's enum Module

Somewhere in almost every codebase there is a function that takes a status argument and compares it against the string "active", or a direction that is secretly the integer 0. These magic values work right up until someone typos "activ", or forgets whether 1 meant north or south, or an IDE offers zero help autocompleting a bare string. Python's enum module fixes this by letting you define a fixed set of named, immutable, self-documenting constants that group together as a proper type. This article walks through enum from the basics to the parts people trip over.

The problem enums solve

Consider a function guarded by string flags:

def set_state(state):
    if state == "active":
        ...
    elif state == "closed":
        ...

set_state("cvlosed")  # typo — no error, silently does nothing

Nothing catches the typo, the valid values live only in your head, and there is no single place that documents them. An enum turns that loose set of strings into a named type your tools understand.

Your first Enum

Subclass Enum and assign values to member names. Each member is a singleton object with a .name and a .value:

from enum import Enum

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

print(Color.RED)          # Color.RED
print(Color.RED.name)     # 'RED'
print(Color.RED.value)    # 1

You can look members up by value (calling the class) or by name (subscripting it), and iterate the class in definition order:

print(Color(2))        # Color.GREEN   (lookup by value)
print(Color['BLUE'])   # Color.BLUE    (lookup by name)
print(list(Color))     # [, , ]

Members are singletons, so identity comparison works and is the idiomatic way to compare them:

print(Color.RED is Color.RED)   # True
print(Color.RED == Color.RED)   # True
print(Color.RED == 1)           # False — a plain Enum is not its value

That last line is important: a plain Enum member is not equal to its underlying value. Color.RED == 1 is False. This is a feature — it stops you from accidentally mixing colors with raw integers — but it surprises people coming from languages where enums are just labelled ints.

Letting Python assign values with auto()

When the specific values do not matter and you only care about the names, auto() assigns sequential integers for you:

from enum import Enum, auto

class Direction(Enum):
    NORTH = auto()
    SOUTH = auto()
    EAST = auto()
    WEST = auto()

print([d.value for d in Direction])   # [1, 2, 3, 4]

Using auto() signals intent clearly: "these are distinct labels, don't read anything into the numbers." If you later need to control what auto() produces, override _generate_next_value_ on the class.

Enums are real classes: add methods and rich members

An enum is an ordinary class, so members can carry more than one piece of data and the enum can have methods. A common pattern is to give each member a tuple and unpack it in __init__:

from enum import Enum

class Planet(Enum):
    MERCURY = (3.303e+23, 2.4397e6)
    EARTH   = (5.976e+24, 6.37814e6)

    def __init__(self, mass, radius):
        self.mass = mass       # kilograms
        self.radius = radius   # meters

    @property
    def gravity(self):
        G = 6.67300e-11
        return G * self.mass / (self.radius * self.radius)

print(f"{Planet.EARTH.gravity:.2f}")   # 9.80

Here the tuple is the member's .value, but __init__ spreads it into readable attributes, and gravity is computed on demand. This keeps related data and behaviour bundled with the constant it belongs to.

IntEnum: when you really do want an int

Sometimes a value must interoperate with integers — a protocol code, an HTTP status, a database column. IntEnum members are integers, so comparisons and arithmetic against plain ints work:

from enum import IntEnum

class Status(IntEnum):
    PENDING = 1
    ACTIVE  = 2
    CLOSED  = 3

print(Status.ACTIVE == 2)            # True
print(Status.ACTIVE < Status.CLOSED) # True
print(sorted([Status.CLOSED, Status.PENDING]))

The trade-off is that this looseness is exactly what a plain Enum protects you from. Reach for IntEnum only when integer compatibility is a genuine requirement, not just for convenience. There is a matching StrEnum (added in Python 3.11) whose members are also real str instances — handy for values that flow through JSON or URLs:

from enum import StrEnum   # Python 3.11+

class Env(StrEnum):
    DEV  = "dev"
    PROD = "prod"

print(Env.PROD == "prod")   # True

Flag: combinable bitmask options

For sets of on/off options that combine, Flag supports the bitwise operators |, &, ^, and ~. Use auto() so each flag gets a distinct power-of-two value:

from enum import Flag, auto

class Perm(Flag):
    READ    = auto()
    WRITE   = auto()
    EXECUTE = auto()

access = Perm.READ | Perm.WRITE

print(Perm.READ in access)      # True
print(Perm.EXECUTE in access)   # False
print(bool(access & Perm.WRITE))# True

This is far more readable than juggling raw integer masks like 0b110, and membership tests read like plain English. If you need the individual flags to also behave as integers, IntFlag is the bit-compatible variant.

Aliases and the @unique guard

If two members share the same value, the second becomes an alias of the first rather than a separate member. Aliases do not appear in iteration:

from enum import Enum

class Shade(Enum):
    RED     = 1
    CRIMSON = 1   # alias for RED

print(Shade.CRIMSON is Shade.RED)   # True
print(list(Shade))                  # [] — alias hidden

Aliases are occasionally useful (two spellings, one concept), but they are more often a copy-paste bug. When every member must be distinct, decorate the class with @unique to turn accidental duplicates into an error at definition time:

from enum import Enum, unique

@unique
class Weekday(Enum):
    MON = 1
    TUE = 2
    WED = 2   # ValueError: duplicate values found

The functional API

You can build an enum in one call, which is handy when the members come from data:

from enum import Enum

Animal = Enum('Animal', ['CAT', 'DOG', 'BIRD'])
print(list(Animal))       # [, ...]
print(Animal.DOG.value)   # 2

The names can be a list (values auto-number from 1), a space-separated string, or an explicit mapping of names to values for full control.

Common pitfalls

Don't compare a plain Enum to its value. Color.RED == 1 is False. Compare members to members, and use is for the clearest intent.

Mixed-in types format by their value. Because IntEnum mixes in int, an f-string formats it as the number even though str() may show the name:

from enum import IntEnum
class Status(IntEnum):
    ACTIVE = 2

print(f"{Status.ACTIVE}")   # '2'  — int formatting wins

If you want a stable, human-readable label regardless of the mixed-in type, define __str__ explicitly or reference .name. (Note that the exact str()/repr() output of enums has shifted across Python versions, so don't rely on it for parsing — use .name and .value.)

Members are immutable singletons. You cannot add members after the class is defined or reassign a member's value, which is exactly what makes them safe to pass around.

Handle unknown values gracefully. Calling Color(99) raises ValueError. To accept extra inputs (say, case-insensitive strings), implement a _missing_ classmethod:

from enum import Enum

class Role(Enum):
    ADMIN = "admin"
    USER  = "user"

    @classmethod
    def _missing_(cls, value):
        if isinstance(value, str):
            for member in cls:
                if member.value == value.lower():
                    return member
        return None

print(Role("ADMIN"))   # Role.ADMIN

Wrap-up and next steps

Enums replace scattered magic numbers and stringly-typed flags with a single, named, self-documenting type. Start with a plain Enum and auto() for most cases; reach for IntEnum or StrEnum only when you genuinely need value compatibility; use Flag for combinable options; and add @unique whenever duplicate values would be a bug. From here, explore the enum docs for IntFlag, custom _generate_next_value_ logic, and the 3.11+ additions like StrEnum and the member/nonmember helpers. Once enums are part of your vocabulary, a surprising amount of defensive if value not in (...) code simply disappears.