typing.Literal en Python: Restringe Valores resuelve un problema frecuente en proyectos Python: Expresa que una entrada acepta valores concretos y no cualquier string o entero. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
Literal informa al verificador que solo son válidos los valores listados. Funciona bien para modos, estados y etiquetas de uniones.
Para repasar los fundamentos relacionados, consulta también la guía de type hints. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
from typing import Literal
type Mode = Literal["read", "write", "append"]
def open_store(mode: Mode) -> None:
...
open_store("read")
## open_store("reed") # type checker errorCrea un alias si el conjunto se repite y usa Enum cuando los valores tienen comportamiento, metadatos o deben enumerarse en runtime.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. Literal no valida llamadas en ejecución. Los datos externos aún necesitan validación. Conjuntos enormes son difíciles de mantener.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Ejecuta el type checker con valores válidos e inválidos y conserva pruebas runtime en fronteras JSON o de usuario.