Enum

An enumeration (Enum) in Python is a data structure consisting of a set of bound, symbolic names (members) mapped to constant values. Implemented via the standard library’s enum module, Enums are created by subclassing the Enum base class, providing a namespace where the members behave as immutable, iterable singletons.

from enum import Enum

class Status(Enum):
    PENDING = 1
    ACTIVE = 2
    INACTIVE = 3

Member Access and Attributes

Enum members can be accessed programmatically via three distinct mechanisms: by attribute, by value, or by name. Every member is an instance of its parent Enum class and exposes .name and .value properties.

# Access by attribute
state = Status.ACTIVE


# Access by value (instantiation)
state = Status(2)


# Access by name (dictionary lookup)
state = Status['ACTIVE']


# Property resolution
print(state.name)   # Output: 'ACTIVE'
print(state.value)  # Output: 2

Technical Characteristics

Singleton Identity and Comparison Enum members are singletons in memory. They should be compared using the is operator for identity checks, though equality == is also supported. By default, standard Enum members do not evaluate as equal to their underlying values.

Status.ACTIVE is Status.ACTIVE  # True
Status.ACTIVE == Status.ACTIVE  # True
Status.ACTIVE == 2              # False (Type mismatch: Status vs int)

Immutability Once an Enum class is defined, its members and their corresponding values cannot be modified at runtime. Attempting to reassign a member (e.g., Status.PENDING = 0) raises an AttributeError.

Iteration Enums natively support iteration. Iterating over the Enum class yields its members in the exact order they were defined.

for state in Status:
    print(repr(state))

# <Status.PENDING: 1>

# <Status.ACTIVE: 2>

# <Status.INACTIVE: 3>

Aliasing and the @unique Decorator

If multiple members in an Enum are assigned the same value, the first defined member becomes the primary member, and subsequent members become aliases. Aliases are excluded during standard iteration.

To strictly enforce value uniqueness at class creation time, Python provides the @unique decorator.

from enum import Enum, unique

@unique
class ErrorCode(Enum):
    NOT_FOUND = 404
    MISSING = 404  # Raises ValueError: duplicate values found

Automatic Value Generation

The auto() helper function automatically generates values for Enum members, delegating the exact value assignment to the _generate_next_value_ method (which defaults to incrementing integers starting at 1).

from enum import Enum, auto

class Signal(Enum):
    RED = auto()    # 1
    YELLOW = auto() # 2
    GREEN = auto()  # 3

Specialized Enum Base Classes

Python provides specialized Enum variants to alter comparison behavior and support specific operations:

• IntEnum: Members are subclasses of both the Enum type and the built-in int. Unlike standard Enums, IntEnum members can be compared directly to integers and used in mathematical operations.

from enum import IntEnum

class Priority(IntEnum):
    LOW = 1
    HIGH = 2

Priority.LOW == 1  # True

• Flag and IntFlag: Designed to support bitwise operations (|, &, ^, ~). Members can be combined to create complex, multi-state values.

from enum import Flag, auto

class Permissions(Flag):
    READ = auto()    # 1
    WRITE = auto()   # 2
    EXECUTE = auto() # 4

# Bitwise OR combination
user_perms = Permissions.READ | Permissions.WRITE

# Bitwise AND check
has_read = bool(user_perms & Permissions.READ) # True

Master Python with Deep Grasping Methodology!

Learn More