Enums

Enumerações substituem strings e inteiros mágicos por constantes nomeadas e tipadas. Membros são singletons - estáveis em identidade e auto-documentados em APIs, configurações e instruções match.

Receita

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

Quando usar:

Métodos HTTP, estados de pedido, nomes de roles
Valores de configuração validados contra um conjunto fixo
Ramificação match exaustiva
Permissões de bitmask com Flag

Exemplo de Trabalho

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 "aguardando"
        case Status.ACTIVE:
            return "em execução"
        case Status.CLOSED:
            return "concluído"
 
if __name__ == "__main__":
    print(authorize(Role.ADMIN, Role.DEV))
    print(can_read(ADMIN_PERMS))
    print(describe_status(Status.ACTIVE))

O que isso demonstra:

StrEnum serializa para o valor string para logs JSON
Flag combina com | e testa com in
match em membros de enum para tratamento exaustivo
auto() gera valores para enums não-string

Mergulho Profundo

Como Funciona

EnumMeta - Cria objetos de membro únicos na definição da classe.
Valor vs Identidade - Status.ACTIVE is Status.ACTIVE sempre Verdadeiro.
StrEnum - Subclasse de str e Enum - compara igual ao seu valor string.
IntEnum - Subclasse de int - use com cautela quando precisar de comportamento de int.
API Funcional - Enum('Color', ['RED', 'GREEN']) para enums dinâmicos.

Variedades de Enum

Classe	Tipo de Membro
`Enum`	Genérico
`StrEnum`	str
`IntEnum`	int
`Flag`	bitmask int

Notas Python

# Serialização JSON
status = Status.ACTIVE
payload = {"status": status}  # StrEnum -> "active" em muitos codificadores
 
# obter por valor
Status("active")  # retorna Status.ACTIVE

Armadilhas

IntEnum isinstance int - Passa para funções que esperam int, mas pode confundir verificadores de tipo. Correção: Prefira StrEnum ou Enum simples.
Comparando com strings brutas sem StrEnum - Status.ACTIVE == "active" Falso em Enum simples. Correção: StrEnum ou compare .value.
Valores duplicados como alias - O segundo nome é um alias para o primeiro membro. Correção: Use o decorador @enum.unique.
Membros de enum mutáveis - Não é possível atribuir novos atributos a membros. Correção: Anexe dados via Enum com valores de tupla (nome, extra).
Membros de Flag infinitos - Flags combinadas criam membros compostos. Correção: Documente valores compostos ou use subconjuntos explícitos.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`Literal["a","b"]`	Apenas dicas de tipo	Precisa de validação em tempo de execução
const strings de módulo	Scripts minúsculos	Estabilidade da API é importante
Pydantic `Literal`	Validação HTTP	Enums de domínio interno
tabela de consulta de banco de dados	Valores dinâmicos definidos pelo usuário	Estados fixos do sistema

FAQs

Enum vs Literal?

Enum são objetos em tempo de execução com identidade. Literal é apenas para tipagem estática de strings fixas.

StrEnum JSON?

Frequentemente serializa como valor string - verifique com seu codificador JSON (stdlib json usa o valor para StrEnum).

Como obter todos os membros?

list(Status) ou Status.__members__.values().

decorador unique?

@unique na classe Enum levanta um erro se dois nomes mapeiam para o mesmo valor não intencionalmente.

operadores Flag?

| união, & interseção, ~ inverter dentro da definição de Flag.

enum em match?

Correspondência exaustiva - mypy/pyright alertam sobre casos ausentes com configurações estritas.

estender Enum?

Subclasse de Enum não é recomendada, exceto em casos especiais - componha em vez disso.

valores auto()?

Inteiros incrementando a partir de um - substitua se valores estáveis forem necessários entre versões.

escolhas Django?

TextChoices/IntegerChoices são wrappers de enum do Django - padrões semelhantes.

armazenamento em banco de dados?

Armazene .value na coluna; reconstrua com Enum(value) ao ler.

Relacionados

Fluxo de Controle - match/case
Noções Básicas de Dicas de Tipo - Tipos Literal
Literal, Final & Anotado - constantes precisas
dataclasses - campos enum em registros

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.

Enums

Receita

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

Quando usar:

Métodos HTTP, estados de pedido, nomes de roles
Valores de configuração validados contra um conjunto fixo
Ramificação match exaustiva
Permissões de bitmask com Flag

Exemplo de Trabalho

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 "aguardando"
        case Status.ACTIVE:
            return "em execução"
        case Status.CLOSED:
            return "concluído"
 
if __name__ == "__main__":
    print(authorize(Role.ADMIN, Role.DEV))
    print(can_read(ADMIN_PERMS))
    print(describe_status(Status.ACTIVE))

O que isso demonstra:

StrEnum serializa para o valor string para logs JSON
Flag combina com | e testa com in
match em membros de enum para tratamento exaustivo
auto() gera valores para enums não-string

Mergulho Profundo

Como Funciona

EnumMeta - Cria objetos de membro únicos na definição da classe.
Valor vs Identidade - Status.ACTIVE is Status.ACTIVE sempre Verdadeiro.
StrEnum - Subclasse de str e Enum - compara igual ao seu valor string.
IntEnum - Subclasse de int - use com cautela quando precisar de comportamento de int.
API Funcional - Enum('Color', ['RED', 'GREEN']) para enums dinâmicos.

Variedades de Enum

Classe	Tipo de Membro
`Enum`	Genérico
`StrEnum`	str
`IntEnum`	int
`Flag`	bitmask int

Notas Python

# Serialização JSON
status = Status.ACTIVE
payload = {"status": status}  # StrEnum -> "active" em muitos codificadores
 
# obter por valor
Status("active")  # retorna Status.ACTIVE

Armadilhas

IntEnum isinstance int - Passa para funções que esperam int, mas pode confundir verificadores de tipo. Correção: Prefira StrEnum ou Enum simples.
Comparando com strings brutas sem StrEnum - Status.ACTIVE == "active" Falso em Enum simples. Correção: StrEnum ou compare .value.
Valores duplicados como alias - O segundo nome é um alias para o primeiro membro. Correção: Use o decorador @enum.unique.
Membros de enum mutáveis - Não é possível atribuir novos atributos a membros. Correção: Anexe dados via Enum com valores de tupla (nome, extra).
Membros de Flag infinitos - Flags combinadas criam membros compostos. Correção: Documente valores compostos ou use subconjuntos explícitos.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`Literal["a","b"]`	Apenas dicas de tipo	Precisa de validação em tempo de execução
const strings de módulo	Scripts minúsculos	Estabilidade da API é importante
Pydantic `Literal`	Validação HTTP	Enums de domínio interno
tabela de consulta de banco de dados	Valores dinâmicos definidos pelo usuário	Estados fixos do sistema

FAQs

Enum vs Literal?

Enum são objetos em tempo de execução com identidade. Literal é apenas para tipagem estática de strings fixas.

StrEnum JSON?

Frequentemente serializa como valor string - verifique com seu codificador JSON (stdlib json usa o valor para StrEnum).

Como obter todos os membros?

list(Status) ou Status.__members__.values().

decorador unique?

@unique na classe Enum levanta um erro se dois nomes mapeiam para o mesmo valor não intencionalmente.

operadores Flag?

| união, & interseção, ~ inverter dentro da definição de Flag.

enum em match?

Correspondência exaustiva - mypy/pyright alertam sobre casos ausentes com configurações estritas.

estender Enum?

Subclasse de Enum não é recomendada, exceto em casos especiais - componha em vez disso.

valores auto()?

Inteiros incrementando a partir de um - substitua se valores estáveis forem necessários entre versões.

escolhas Django?

TextChoices/IntegerChoices são wrappers de enum do Django - padrões semelhantes.

armazenamento em banco de dados?

Armazene .value na coluna; reconstrua com Enum(value) ao ler.

Relacionados

Fluxo de Controle - match/case
Noções Básicas de Dicas de Tipo - Tipos Literal
Literal, Final & Anotado - constantes precisas
dataclasses - campos enum em registros

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+, e uv 0.6+.

Enums

Buscar na documentação

Enums