Enum: constantes nomeadas e seguras

O problema dos valores mágicos

Espalhar números e textos soltos pelo código é uma fonte silenciosa de bugs. Se o status de um pedido é representado pelo texto pendente em um lugar, Pendente com maiúscula em outro e o número 1 em um terceiro, cedo ou tarde alguém compara errado e o programa se comporta de forma estranha, sem estourar erro. Esses são os valores mágicos: dados soltos cujo significado mora só na cabeça de quem escreveu. O Enum resolve isso ao reunir as opções possíveis em constantes nomeadas.

from enum import Enum

class Status(Enum):
    PENDENTE = "pendente"
    PAGO = "pago"
    CANCELADO = "cancelado"

pedido = Status.PENDENTE
print(pedido)         # Status.PENDENTE
print(pedido.value)   # pendente
print(pedido.name)    # PENDENTE

if pedido is Status.PENDENTE:
    print("Aguardando pagamento")

Status.PENDENTE é uma constante nomeada; o valor solto pendente fica encapsulado.

Com o Enum, o código passa a falar em Status.PENDENTE em vez do texto pendente cru. Cada membro tem um name, o nome legível, e um value, o valor associado. A comparação é feita por identidade, com is, o que é seguro e claro. E há uma vantagem discreta e poderosa: se você digitar Status.PENDNTE errado, o Python avisa na hora, porque esse membro não existe, enquanto o texto pendnte passaria despercebido. O Enum transforma erros silenciosos em erros barulhentos.

Iterar pelos membros e comparar

Um Enum não é só um punhado de constantes: é um tipo que você pode percorrer. Iterar sobre a classe do Enum dá todos os membros na ordem em que foram definidos, o que serve para montar menus, validar entradas ou listar as opções disponíveis. Você também pode recuperar um membro a partir do seu valor, útil para converter um dado externo, como o texto vindo de um formulário, no membro correspondente. Isso concentra num lugar só a lista de opções válidas do sistema.

from enum import Enum

class Prioridade(Enum):
    BAIXA = 1
    MEDIA = 2
    ALTA = 3

# Iterar por todos os membros:
for p in Prioridade:
    print(p.name, p.value)
# BAIXA 1 / MEDIA 2 / ALTA 3

# Recuperar um membro pelo valor:
print(Prioridade(2))       # Prioridade.MEDIA
# Recuperar pelo nome:
print(Prioridade["ALTA"])  # Prioridade.ALTA

Percorrer o Enum lista os membros; também dá para buscar por valor ou por nome.

Variações úteis do Enum

O Enum tem parentes para casos específicos. Quando você não se importa com o valor de cada membro, só com o nome, a função auto atribui números automáticos e evita digitar valores à toa. Quando os membros precisam se comportar como números de verdade, por exemplo para comparação de ordem ou uso em cálculos, existe o IntEnum, cujos membros são inteiros para todos os efeitos. E há o Flag, para combinar opções com operações de bit. Na maioria dos casos, o Enum comum já basta.

from enum import Enum, IntEnum, auto

class Direcao(Enum):
    NORTE = auto()
    SUL = auto()
    LESTE = auto()
    OESTE = auto()

print(Direcao.NORTE.value)  # 1  (auto numerou)

class Nivel(IntEnum):
    BAIXO = 1
    ALTO = 3

print(Nivel.ALTO > Nivel.BAIXO)  # True  (IntEnum compara como inteiro)
print(Nivel.ALTO + 1)            # 4     (comporta-se como int)

auto numera os membros sozinho; IntEnum faz os membros agirem como inteiros.

Com o Enum você fecha o repertório de modelagem de dados deste módulo. Ele é a ferramenta certa toda vez que uma variável só pode assumir um conjunto fixo e conhecido de valores: estados de um pedido, dias da semana, níveis de acesso, tipos de uma operação. Trocar valores mágicos por constantes nomeadas deixa o código mais legível, mais seguro contra erros de digitação e mais fácil de manter. Junto com dataclass, field, frozen e namedtuple, o Enum completa o kit de estruturar dados com intenção em Python.