Enumerations in Python

Enumerations are a set of symbolic names bound to unique, constant values. Within an enumeration in Python, the members can be compared, and the enumeration itself can be iterated over. Because Enums are used to represent constants, it is recommended to use UPPER_CASE names for enum members.

Enum Types

enum module in Python defines four enumeration classes that can be used to define unique sets of names and values. These are

Enum : Base class for creating enumerated constants
IntEnum : Base class for creating enumerated constants. It is a subclasses of int.
Flag : Base class for creating enumerated constants that can be combined using the bitwise operations.
IntFlag : Base class for creating enumerated constants that can be combined using the bitwise operators. It is a subclasses of int.

Creating Enum

To define an enumeration, subclass Enum as follows:

from enum import Enum

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3
    PEAR = 4

Here we create an Enumeration class called Fruit. Class attributes (enumeration members) are constants.

Member values can be anything: int, str, etc. If the exact value is not required, you may use auto and an appropriate value will be assigned. The enum members have names and values. Following example demonstrate this.

# Enumerations using the Enum base class
from enum import Enum, auto

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3

    # Using auto() for assigning value
    PEAR = auto()

# Type
print(type(Fruit.APPLE))

# Output
# <enum 'Fruit'>

print(repr(Fruit.APPLE))

# Output
# <Fruit.APPLE: 1>

# Name and Value
print(Fruit.APPLE.name, Fruit.APPLE.value)

# Output
# APPLE 1

# Auto-generated value
print(Fruit.PEAR.value)

# Output
# 4

Enum also supports iteration. Below example shows the use of for loop with enumeration.

from enum import Enum

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3
    PEAR = 4

for fruit in Fruit:
    print(fruit)

# Output
# Fruit.APPLE
# Fruit.BANANA
# Fruit.ORANGE
# Fruit.PEAR

Unique Values

More than one enum members with the same name is invalid. However, two enum members can have the same value as shown in below example.

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    # ORANGE = 4   -> Invalid
    ORANGE = 3
    PEAR = 3      # Two member can have same value

When duplicate values are not allowed as shown above, unique decorator can be used to ensure each value is used only once in the enumeration. If any duplicate values are found, a ValueError exception is raised. Below example shows use of unique decorator.

from enum import Enum, unique

@unique
class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3
    PEAR = 4

Accessing Member

Enum members can be accesses using their name. However Python has support to access members in enumerations programmatically. If you have an enum member variable, we can get its name and value.

from enum import Enum

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3
    PEAR = 4

print(Fruit.APPLE)

# Output
# Fruit.APPLE

# Accessing using value
print(Fruit(1))

# Output
# Fruit.APPLE

# Accessing using name
print(Fruit['BANANA'])

# Output
# Fruit.BANANA

fruit = Fruit.APPLE
print(fruit.name, fruit.value)

# Output
# APPLE 1

Comparisons

Enum supports comparison by identity. Ordered comparisons between enumeration values are not supported.

from enum import Enum

class Fruit(Enum):
    APPLE = 1
    BANANA = 2
    ORANGE = 3
    PEAR = 4

print(Fruit.APPLE is Fruit.PEAR)

# Output
# False

# Below is illegal
# print(Fruit.APPLE < Fruit.PEAR)