Of course! Let's dive deep into Python's enum module, which is used for creating enumerations.

What is an Enumeration?

An enumeration (or enum) is a set of symbolic names (members) bound to unique, constant values. Think of it as a way to define a group of related constants in a more readable, organized, and type-safe way.

Before enum was introduced in Python 3.4, the common way to simulate an enum was to use simple class attributes:

# The "old" way before enum
class Color:
    RED = 1
    GREEN = 2
    BLUE = 3
# This works, but it's not type-safe and has some quirks
print(Color.RED)        # Output: 1
print(Color.RED.name)   # AttributeError: 'int' object has no attribute 'name'

The enum module provides a robust, standardized, and powerful way to achieve this.

Basic Usage: The Enum Class

The simplest way to create an enumeration is by subclassing enum.Enum.

import enum
class Color(enum.Enum):
    RED = 1
    GREEN = 2
    BLUE = 3
# --- Accessing Members ---
# 1. By name (most common)
red_member = Color.RED
print(f"Member: {red_member}")
print(f"Name: {red_member.name}")   # The symbolic name ('RED')
print(f"Value: {red_member.value}") # The assigned value (1)
# 2. By value
green_member = Color(2)
print(f"\nMember from value 2: {green_member}")
# 3. By name
blue_member = Color['BLUE']
print(f"Member from name 'BLUE': {blue_member}")
# --- Iterating over Members ---
print("\n--- All Colors ---")
for color in Color:
    print(f"{color.name}: {color.value}")

Output:

Member: Color.RED
Name: RED
Value: 1
Member from value 2: Color.GREEN
Member from name 'BLUE': Color.BLUE
--- All Colors ---
RED: 1
GREEN: 2
BLUE: 3

Key Features and Benefits

Type Safety

This is one of the biggest advantages. You can't accidentally assign a value that isn't part of the enumeration.

def set_background(color: Color):
    print(f"Setting background to {color.name}")
# This works perfectly
set_background(Color.RED)
# This will raise a TypeError at runtime, which is great for catching bugs!
try:
    set_background(1) # An integer, not a Color member
except TypeError as e:
    print(f"\nError caught: {e}")

Auto-Values

You don't have to assign integer values manually. The enum module can do it for you.

class Status(enum.Enum):
    PENDING = enum.auto()
    RUNNING = enum.auto()
    SUCCESS = enum.auto()
    FAILED = enum.auto()
for status in Status:
    print(f"{status.name}: {status.value}")

Output:

PENDING: 1
RUNNING: 2
SUCCESS: 3
FAILED: 4

enum.auto() automatically assigns values starting from 1, just like enumerate().

Comparison

Enum members are compared by identity, not by value. This prevents confusion between different enum types.

class Planet(enum.Enum):
    MERCURY = (3.303e+23, 2.4397e6)
    EARTH   = (5.976e+24, 6.37814e6)
# Members are singletons. Two references to the same member are the same object.
print(Color.RED is Color.RED) # True
# Members from different enums are not the same, even if values match
class OtherColor(enum.Enum):
    RED = 'red'
print(Color.RED is OtherColor.RED) # False
# Comparison by value is possible but not the primary way
print(Color.RED.value == OtherColor.RED.value) # True

Different Enum Types

The enum module provides several base classes, each with different behaviors for the values.

enum.IntEnum

This is a great choice when you need your enum members to behave like integers for arithmetic operations and comparisons. It inherits from both int and Enum.

class Priority(enum.IntEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3
# You can perform arithmetic
print(f"HIGH is greater than MEDIUM: {Priority.HIGH > Priority.MEDIUM}")
print(f"Priority.HIGH + 1 = {Priority.HIGH + 1}") # This results in 4, which is not an enum member!
# You can compare with integers directly
print(f"Priority.MEDIUM == 2: {Priority.MEDIUM == 2}")

enum.Flag

This is designed for sets of flags that can be combined using bitwise operators (, &, , ^). Each member's value should be a power of two.

class Permission(enum.Flag):
    READ = 1      # 0b0001
    WRITE = 2     # 0b0010
    EXECUTE = 4   # 0b0100
    ADMIN = 8     # 0b1000
# Combine flags using the bitwise OR operator
user_permissions = Permission.READ | Permission.WRITE
print(f"User permissions: {user_permissions}") # Permission.READ|WRITE
print(f"Value: {user_permissions.value}")      # 3 (which is 0b0011)
# Check for a specific flag using bitwise AND
print(f"Can user read? {bool(user_permissions & Permission.READ)}")    # True
print(f"Can user execute? {bool(user_permissions & Permission.EXECUTE)}") # False
# Adding a new flag that is a combination of existing ones
user_permissions |= Permission.EXECUTE
print(f"New permissions: {user_permissions}") # Permission.READ|WRITE|EXECUTE

Advanced Features

Customizing Values

Values don't have to be simple integers. They can be tuples, strings, or any other type.

class Planet(enum.Enum):
    MERCURY = (3.303e+23, 2.4397e6)
    VENUS   = (4.869e+24, 6.0518e6)
    EARTH   = (5.976e+24, 6.37814e6)
    def __init__(self, mass, radius):
        self.mass = mass      # in kg
        self.radius = radius  # in meters
    @property
    def surface_gravity(self):
        # G is the gravitational constant
        G = 6.67300e-11
        return G * self.mass / (self.radius * self.radius)
print(f"Earth's mass: {Planet.EARTH.mass} kg")
print(f"Earth's surface gravity: {Planet.EARTH.surface_gravity:.2f} m/s^2")

Creating Members Dynamically

If you need to create an enum class programmatically, you can use the Enum function.

# The first argument is the name of the enum class
# The second is a mapping of names to values
Mode = enum.Enum('Mode', {'ON': 'on', 'OFF': 'off', 'STANDBY': 'standby'})
print(Mode.ON)
print(Mode.ON.value)

enum.unique()

A decorator that ensures all members in an enum have unique values. If you try to create an enum with duplicate values, it will raise a ValueError.

try:
    @enum.unique
    class DuplicateValue(enum.Enum):
        A = 1
        B = 2
        C = 1 # This will cause an error
except ValueError as e:
    print(f"Error: {e}")

Summary: When to Use enum

By using Python's enum module, you can write code that is more readable, less error-prone, and more maintainable.