Enumeraciones

Las enumeraciones reemplazan cadenas y enteros "mágicos" con constantes con nombre y tipadas. Los miembros son singletons: estables en identidad y auto-documentados en APIs, configuraciones y sentencias match.

Receta

from enum import StrEnum, auto
 
class Status(StrEnum):
    PENDING = "pending"
    ACTIVE = "active"
    CLOSED = "closed"
 
class Priority(StrEnum):
    LOW = auto()
    MEDIUM = auto()
    HIGH = auto()

Cuándo usar esto:

• Métodos HTTP, estados de pedidos, nombres de roles
• Valores de configuración validados contra un conjunto fijo
• Ramificación match exhaustiva
• Permisos de máscara de bits con Flag

Ejemplo de Trabajo

from enum import Flag, StrEnum, auto
 
class Status(StrEnum):
    PENDING = "pending"
    ACTIVE = "active"
    CLOSED = "closed"
 
class Role(StrEnum):
    ADMIN = "admin"
    DEV = "dev"
    VIEWER = "viewer"
 
class Permission(Flag):
    READ = auto()
    WRITE = auto()
    EXECUTE = auto()
 
ADMIN_PERMS = Permission.READ | Permission.WRITE | Permission.EXECUTE
 
def authorize(role: Role, required: Role) -> bool:
    hierarchy = {Role.VIEWER: 0, Role.DEV: 1, Role.ADMIN: 2}
    return hierarchy[role] >= hierarchy[required]
 
def can_read(perms: Permission) -> bool:
    return Permission.READ in perms
 
def describe_status(status: Status) -> str:
    match status:
        case Status.PENDING:
            return "esperando"
        case Status.ACTIVE:
            return "en ejecución"
        case Status.CLOSED:
            return "terminado"
 
if __name__ == "__main__":
    print(authorize(Role.ADMIN, Role.DEV))
    print(can_read(ADMIN_PERMS))
    print(describe_status(Status.ACTIVE))

Lo que esto demuestra:

• StrEnum se serializa a su valor de cadena para logs JSON
• Flag se combina con | y se prueba con in
• match sobre miembros de enumeración para un manejo exhaustivo
• auto() genera valores para enumeraciones que no son de cadena

Análisis Profundo

Cómo Funciona

• EnumMeta - Crea objetos miembro únicos en la definición de la clase.
• Valor vs identidad - Status.ACTIVE is Status.ACTIVE siempre es Verdadero.
• StrEnum - Subclase de str y Enum - compara igual a su valor de cadena.
• IntEnum - Subclase de int - úselo con precaución cuando necesite comportamiento de int.
• API Funcional - Enum('Color', ['RED', 'GREEN']) para enumeraciones dinámicas.

Variedades de Enumeración

Notas de Python

# Serialización JSON
status = Status.ACTIVE
payload = {"status": status}  # StrEnum -> "active" en muchos codificadores
 
# obtener por valor
Status("active")  # devuelve Status.ACTIVE

Trampas Comunes

• IntEnum isinstance int - Pasa a funciones que esperan int pero puede confundir a los verificadores de tipos. Solución: Prefiera StrEnum o Enum simple.
• Comparar con cadenas sin procesar sin StrEnum - Status.ACTIVE == "active" es Falso en Enum simple. Solución: StrEnum o comparar .value.
• Valores duplicados como alias - El segundo nombre es un alias del primer miembro. Solución: Use el decorador @enum.unique.
• Miembros de enumeración mutables - No se pueden asignar nuevos atributos a los miembros. Solución: Adjunte datos a través de Enum con valores de tupla (nombre, extra).
• Miembros infinitos de Flag - Las banderas combinadas crean miembros compuestos. Solución: Documente los valores compuestos o use subconjuntos explícitos.

Alternativas

Preguntas Frecuentes

Relacionado

• Flujo de Control - match/case
• Conceptos Básicos de Type Hints - Tipos Literal
• Literal, Final y Annotated - constantes precisas
• dataclasses - campos de enumeración en registros

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.