Enumerations

The enum.Enum class behaves differently from other Python classes in several ways that require special-case handling in type checkers. This section discusses the Enum behaviors that should be supported by type checkers and others which may be supported optionally. It is recommended that library and type stub authors avoid using optional behaviors because these may not be supported by some type checkers.

Enum Definition

Enum classes can be defined using a “class syntax” or a “function syntax”. The function syntax offers several ways to specify enum members: names passed as individual arguments, a list or tuple of names, a string of comma-delimited or space-delimited names, a list or tuple of tuples that contain name/value pairs, and a dictionary of name/value items.

Type checkers should support the class syntax, but the function syntax (in its various forms) is optional:

class Color1(Enum): # Supported
    RED = 1
    GREEN = 2
    BLUE = 3

Color2 = Enum('Color2', 'RED', 'GREEN', 'BLUE')  # Optional
Color3 = Enum('Color3', ['RED', 'GREEN', 'BLUE'])  # Optional
Color4 = Enum('Color4', ('RED', 'GREEN', 'BLUE'))  # Optional
Color5 = Enum('Color5', 'RED, GREEN, BLUE')  # Optional
Color6 = Enum('Color6', 'RED GREEN BLUE')  # Optional
Color7 = Enum('Color7', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])  # Optional
Color8 = Enum('Color8', (('RED', 1), ('GREEN', 2), ('BLUE', 3)))  # Optional
Color9 = Enum('Color9', {'RED': 1, 'GREEN': 2, 'BLUE': 3})  # Optional

Enum classes can also be defined using a subclass of enum.Enum or any class that uses enum.EnumType (or a subclass thereof) as a metaclass. Note that enum.EnumType was named enum.EnumMeta prior to Python 3.11. Type checkers should treat such classes as enums:

class CustomEnum1(Enum):
    pass

class Color7(CustomEnum1):  # Supported
    RED = 1
    GREEN = 2
    BLUE = 3

class CustomEnumType(EnumType):
    pass

class CustomEnum2(metaclass=CustomEnumType):
    pass

class Color8(CustomEnum2):  # Supported
    RED = 1
    GREEN = 2
    BLUE = 3

Enum Behaviors

Enum classes are iterable and indexable, and they can be called with a value to look up the enum member with that value. Type checkers should support these behaviors:

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

for color in Color:
    reveal_type(color)  # Revealed type is 'Color'

reveal_type(Color["RED"])  # Revealed type is 'Literal[Color.RED]' (or 'Color')
reveal_type(Color(3))  # Revealed type is 'Literal[Color.BLUE]' (or 'Color')

Unlike most Python classes, Calling an enum class does not invoke its constructor. Instead, the call performs a value-based lookup of an enum member.

An Enum class with one or more defined members cannot be subclassed. They are implicitly “final”. Type checkers should enforce this:

class EnumWithNoMembers(Enum):
    pass

class Shape(EnumWithNoMembers):  # OK (because no members are defined)
    SQUARE = 1
    CIRCLE = 2

class ExtendedShape(Shape):  # Type checker error: Shape is implicitly final
    TRIANGLE = 3

Defining Members

When using the “class syntax”, enum classes can define both members and other (non-member) attributes. The EnumType metaclass applies a set of rules to distinguish between members and non-members. Type checkers should honor the most common of these rules. The lesser-used rules are optional. Some of these rules may be impossible to evaluate and enforce statically in cases where dynamic values are used.

• If an attribute is defined in the class body with a type annotation but with no assigned value, a type checker should assume this is a non-member attribute:

  class Pet(Enum):
      genus: str  # Non-member attribute
      species: str  # Non-member attribute
  
      CAT = 1  # Member attribute
      DOG = 2  # Member attribute
  

  Within a type stub, members can be defined using the actual runtime values, or a placeholder of ... can be used:

  class Pet(Enum):
      genus: str  # Non-member attribute
      species: str  # Non-member attribute
  
      CAT = 1  # Member attribute with known value and type
      DOG = cast(int, ...)  # Member attribute with unknown value and known type
      BIRD = ...  # Member attribute with unknown value and type
  

• Members defined within an enum class should not include explicit type annotations. Type checkers should infer a literal type for all members. A type checker should report an error if a type annotation is used for an enum member because this type will be incorrect and misleading to readers of the code:

  class Pet(Enum):
      CAT = 1  # OK
      DOG: int = 2  # Type checker error
  

• Methods, callables, descriptors (including properties), and nested classes that are defined in the class are not treated as enum members by the EnumType metaclass and should likewise not be treated as enum members by a type checker:

  def identity(x): return x
  
  class Pet(Enum):
      CAT = 1  # Member attribute
      DOG = 2  # Member attribute
  
      converter = lambda x: str(x)  # Non-member attribute
      transform = identity  # Non-member attribute
  
      @property
      def species(self) -> str:  # Non-member property
          return "mammal"
  
      def speak(self) -> None:  # Non-member method
          print("meow" if self is Pet.CAT else "woof")
  
      class Nested: ... # Non-member nested class
  

• An attribute that is assigned the value of another member of the same enum is not a member itself. Instead, it is an alias for the first member:

  class TrafficLight(Enum):
      RED = 1
      GREEN = 2
      YELLOW = 3
  
      AMBER = YELLOW  # Alias for YELLOW
  
  reveal_type(TrafficLight.AMBER)  # Revealed type is Literal[TrafficLight.YELLOW]
  

• If using Python 3.11 or newer, the enum.member and enum.nonmember classes can be used to unambiguously distinguish members from non-members. Type checkers should support these classes:

  class Example(Enum):
      a = member(1)  # Member attribute
      b = nonmember(2)  # Non-member attribute
  
      @member
      def c(self) -> None:  # Member method
          pass
  
  reveal_type(Example.a)  # Revealed type is Literal[Example.a]
  reveal_type(Example.b)  # Revealed type is int or Literal[2]
  reveal_type(Example.c)  # Revealed type is Literal[Example.c]
  

• An attribute with a private name (beginning with, but not ending in, a double underscore) is treated as a non-member:

  class Example(Enum):
      A = 1  # Member attribute
      __B = 2  # Non-member attribute
  
  reveal_type(Example.A)  # Revealed type is Literal[Example.A]
  reveal_type(Example.__B)  # Type Error: Private name is mangled
  

• An enum class can define a class symbol named _ignore_. This can be a list of names or a string containing a space-delimited list of names that are deleted from the enum class at runtime. Type checkers may support this mechanism:

  class Pet(Enum):
      _ignore_ = "DOG FISH"
      CAT = 1  # Member attribute
      DOG = 2  # temporary variable, will be removed from the final enum class
      FISH = 3  # temporary variable, will be removed from the final enum class
  

Member Names

All enum member objects have an attribute _name_ that contains the member’s name. They also have a property name that returns the same name. Type checkers may infer a literal type for the name of a member:

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

reveal_type(Color.RED._name_)  # Revealed type is Literal["RED"] (or str)
reveal_type(Color.RED.name)  # Revealed type is Literal["RED"] (or str)

def func1(red_or_blue: Literal[Color.RED, Color.BLUE]):
    reveal_type(red_or_blue.name)  # Revealed type is Literal["RED", "BLUE"] (or str)

def func2(any_color: Color):
    reveal_type(any_color.name)  # Revealed type is Literal["RED", "BLUE", "GREEN"] (or str)

Member Values

All enum member objects have an attribute _value_ that contains the member’s value. They also have a property value that returns the same value. Type checkers may infer the type of a member’s value:

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

reveal_type(Color.RED._value_)  # Revealed type is Literal[1] (or int or object or Any)
reveal_type(Color.RED.value)  # Revealed type is Literal[1] (or int or object or Any)

def func1(red_or_blue: Literal[Color.RED, Color.BLUE]):
    reveal_type(red_or_blue.value)  # Revealed type is Literal[1, 2] (or int or object or Any)

def func2(any_color: Color):
    reveal_type(any_color.value)  # Revealed type is Literal[1, 2, 3] (or int or object or Any)

The value of _value_ can be assigned in a constructor method. This technique is sometimes used to initialize both the member value and non-member attributes. If the value assigned in the class body is a tuple, the unpacked tuple value is passed to the constructor. Type checkers may validate consistency between assigned tuple values and the constructor signature:

class Planet(Enum):
    def __init__(self, value: int, mass: float, radius: float):
        self._value_ = value
        self.mass = mass
        self.radius = radius

    MERCURY = (1, 3.303e+23, 2.4397e6)
    VENUS = (2, 4.869e+24, 6.0518e6)
    EARTH = (3, 5.976e+24, 6.37814e6)
    MARS = (6.421e+23, 3.3972e6)  # Type checker error (optional)
    JUPITER = 5  # Type checker error (optional)

reveal_type(Planet.MERCURY.value)  # Revealed type is Literal[1] (or int or object or Any)

The class enum.auto and method _generate_next_value_ can be used within an enum class to automatically generate values for enum members. Type checkers may support these to infer literal types for member values:

class Color(Enum):
    RED = auto()
    GREEN = auto()
    BLUE = auto()

reveal_type(Color.RED.value)  # Revealed type is Literal[1] (or int or object or Any)

If an enum class provides an explicit type annotation for _value_, type checkers should enforce this declared type when values are assigned to _value_:

class Color(Enum):
    _value_: int
    RED = 1 # OK
    GREEN = "green"  # Type error

class Planet(Enum):
    _value_: str

    def __init__(self, value: int, mass: float, radius: float):
        self._value_ = value # Type error

    MERCURY = (1, 3.303e+23, 2.4397e6)

If the literal values for enum members are not supplied, as they sometimes are not within a type stub file, a type checker can use the type of the _value_ attribute:

class ColumnType(Enum):
    _value_: int
    DORIC = ...
    IONIC = ...
    CORINTHIAN = ...

reveal_type(ColumnType.DORIC.value)  # Revealed type is int (or object or Any)

Enum Literal Expansion

From the perspective of the type system, most enum classes are equivalent to the union of the literal members within that enum. (This rule does not apply to classes that derive from enum.Flag because these enums allow flags to be combined in arbitrary ways.) Because of the equivalency between an enum class and the union of literal members within that enum, the two types may be used interchangeably. Type checkers may therefore expand an enum type (that does not derive from enum.Flag) into a union of literal values during type narrowing and exhaustion detection:

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

def print_color1(c: Color):
    if c is Color.RED or c is Color.BLUE:
        print("red or blue")
    else:
        reveal_type(c)  # Revealed type is Literal[Color.GREEN]

def print_color2(c: Color):
    match c:
        case Color.RED | Color.BLUE:
            print("red or blue")
        case Color.GREEN:
            print("green")
        case _:
            reveal_type(c)  # Revealed type is Never

Likewise, a type checker should treat a complete union of all literal members as equivalent to the enum type:

class Answer(Enum):
    Yes = 1
    No = 2

def func(val: object) -> Answer:
    if val is not Answer.Yes and val is not Answer.No:
        raise ValueError("Invalid value")
    reveal_type(val)  # Revealed type is Answer (or Literal[Answer.Yes, Answer.No])
    return val  # OK