typing.Literal em Python: Restrinja Valores resolve um problema recorrente em projetos Python: Expresse que uma entrada aceita valores específicos, não qualquer string ou inteiro. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
Literal informa ao verificador que somente valores literais listados são válidos. Ele é útil em modos, estados e tags de unions.
Para revisar os fundamentos relacionados, consulte também o guia de type hints. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
from typing import Literal
type Mode = Literal["read", "write", "append"]
def open_store(mode: Mode) -> None:
...
open_store("read")
## open_store("reed") # type checker errorCrie um alias quando o conjunto se repetir e prefira Enum quando os valores têm comportamento, metadados ou precisam ser enumerados em runtime.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Literal não valida chamadas em execução. Dados externos ainda precisam de validação. Listas muito grandes tornam a anotação difícil de manter.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Rode o type checker com valores válidos e inválidos e mantenha testes de runtime na fronteira que recebe JSON ou entrada do usuário.