Python Enum Iteration: Loop Over Members

When you define an Enum in Python, you often need to iterate over its members. This article covers python enum iteration: how to loop over members, access names and values, control iteration order, and avoid common mistakes.

What Is an Enum in Python?

An Enum is a class that defines a fixed set of named constants. Each member has a name and a value. Python's enum module provides the Enum base class, which you subclass to create your own enumerations.

from enum import Enum

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

Here, Color.RED is a member with name 'RED' and value 1. The members are instances of the Color class, and they are also attributes of the class.

Iterating Over Enum Members

The simplest way to iterate over all members of an enum is to use a for loop directly on the class. The Enum class implements __iter__, so it behaves like an iterable of its members.

for color in Color:
    print(color)

Output:

Color.RED
Color.GREEN
Color.BLUE

Each color is an enum member. You can use it anywhere you would use a member, such as in comparisons or as a dictionary key.

If you need a list of all members, you can pass the class to list():

colors = list(Color)

This returns [Color.RED, Color.GREEN, Color.BLUE]. The order of members in this list follows their definition order, which is also the iteration order.

Accessing Name and Value During Iteration

While iterating, you often need the member's name or value. Each enum member has two attributes: .name and .value.

for color in Color:
    print(f"{color.name} = {color.value}")

Output:

RED = 1
GREEN = 2
BLUE = 3

You can also use tuple unpacking if you convert each member to a tuple, but that is less common. The direct attribute access is clear and fast.

Iteration Order and How to Control It

By default, enum members are iterated in the order they were defined. This order is stored in the __members__ attribute, which is an ordered dictionary mapping names to members.

for name, member in Color.__members__.items():
    print(name, member.value)

This gives the same output as before. If you need a different order, you can sort the members based on a key. For example, to iterate by value:

for member in sorted(Color, key=lambda m: m.value):
    print(member)

If your enum values are not naturally sortable, you can provide a custom key. Keep in mind that sorting adds overhead, so only do it when the order matters for your logic.

Filtering and Transforming Enum Members

Iteration pairs well with comprehensions. You can filter members based on their name or value, or create a mapping from values to members.

# Filter members with even values
even_members = [m for m in Color if m.value % 2 == 0]

# Create a dict mapping values to members
value_to_member = {m.value: m for m in Color}

The resulting list or dict can be used for fast lookups. For example, if you receive a numeric value from an external system, value_to_member.get(value) is a safe way to convert it to an enum member without raising an exception.

Performance and Memory Considerations

Iterating over an enum is O(n) in the number of members, which is negligible for typical enums with a handful of entries. The members themselves are singletons, so they do not consume extra memory each time you access them.

If you need to perform many lookups by value, building a dictionary once and reusing it is more efficient than scanning the enum each time. This is especially true if the enum has many members or the lookup happens inside a hot loop.

# Build once
lookup = {m.value: m for m in Color}

# Use many times
color = lookup.get(2)

This avoids repeated iteration and makes the intent clearer. However, do not pre-optimize: for most applications, direct iteration is perfectly fine.

Common Mistakes and Edge Cases

One common mistake is assuming that enum members are ordered by value. They are not; they are ordered by definition. If your values are not in the same order as the definitions, iterating directly will not produce a value-sorted sequence.

Another edge case involves aliases. If you define two names with the same value, Python treats the second name as an alias and does not include it in iteration.

class Status(Enum):
    ACTIVE = 1
    ENABLED = 1  # alias for ACTIVE
    INACTIVE = 2

for status in Status:
    print(status)

Output:

Status.ACTIVE
Status.INACTIVE

Status.ENABLED is not iterated because it is an alias. If you need to include aliases, you must iterate over __members__.values() instead, which contains all names.

Using Enum Iteration in Real-World Code

A practical use case is generating a list of choices for a form or API. For example, you might have an enum of user roles and need to present them in a dropdown.

from enum import Enum

class Role(Enum):
    ADMIN = 'admin'
    EDITOR = 'editor'
    VIEWER = 'viewer'

# Build a list of (value, label) tuples for a dropdown
choices = [(role.value, role.name.title()) for role in Role]

This produces [('admin', 'Admin'), ('editor', 'Editor'), ('viewer', 'Viewer')]. The iteration is straightforward and the resulting list can be passed directly to a web framework's choice field.

Another common pattern is validating that an input string matches a member name. You can iterate and compare, but a more efficient approach is to build a set of valid names once:

valid_names = {member.name for member in Role}

if input_name in valid_names:
    role = Role[input_name]

This combines iteration with a set for O(1) membership testing. The set is built once and reused, which is both clear and efficient.

When you work with enums in Python, iteration is a fundamental tool. Understanding how it behaves, how to control order, and how to avoid aliases will help you write more predictable and maintainable code.