Tipado que sirve
Una anotación de tipo en Python es un comentario que una herramienta puede comprobar. No valida nada en ejecución, no ralentiza la llamada y no impide pasar un str donde dice int. Eso es el tipado gradual: útil donde se usa, invisible donde no, y peligroso cuando se confunde con un sistema de tipos real.
En una línea
Sección titulada «En una línea»El tipado no cambia el programa: cambia lo que se puede demostrar sobre el programa antes de ejecutarlo.
Qué hace y qué no
Sección titulada «Qué hace y qué no»def sumar(a: int, b: int) -> int: return a + b
sumar("1", "2") # "12" — no hay errorsumar.__annotations__ # {'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}En ejecución, las anotaciones son un diccionario de metadatos. El error que evita el tipado es el que encontraría mypy al analizar el archivo, no el que lanza Python al llamar.
| Herramienta | Qué comprueba | Cuándo |
|---|---|---|
| Anotaciones | Nada por sí solas | Siempre presentes |
mypy / pyright |
Consistencia estática | En CI o en el editor |
isinstance |
Tipo en runtime | Cuando hay que decidir |
pydantic |
Valida y convierte en runtime | Frontera de datos externos |
Lo que sí cuesta en ejecución
Sección titulada «Lo que sí cuesta en ejecución»| Comprobación | Coste |
|---|---|
isinstance(p, Persona) |
23 ns |
isinstance(p, Protocol) con runtime_checkable |
247 ns |
python mediciones/03-09-11-llamada-tipos.py
Once veces más caro, porque un Protocol en runtime no comprueba herencia: recorre los atributos y métodos declarados y verifica que existan. Es una comprobación estructural hecha a mano en cada llamada.
La consecuencia: @runtime_checkable sirve para isinstance en un if de configuración, no para validar en un bucle. Y no comprueba firmas: un método con los mismos nombres y argumentos distintos pasa el filtro.
Las piezas que valen la pena
Sección titulada «Las piezas que valen la pena»from typing import Protocol, TypedDict, Literal
class Repositorio(Protocol): def obtener(self, id: int) -> dict: ...
class Fila(TypedDict): id: int nombre: str
Modo = Literal["lectura", "escritura"]
def primero[T](items: list[T]) -> T: ... # PEP 695, Python 3.12+Protocoldescribe la forma que debe tener un objeto, sin obligar a heredar. Es duck typing documentado y comprobable.TypedDicttipa un diccionario con claves fijas: útil para JSON y para**kwargs.Literalrestringe a valores concretos:Literal["a", "b"]detecta un"c"en el editor.- Variable de tipo (
[T]en la firma, PEP 695) expresa que la salida tiene el mismo tipo que la entrada (primero([1, 2])esint). En código que debe correr en 3.11, se escribe conTypeVar("T")detyping.
Tipado en la frontera
Sección titulada «Tipado en la frontera»La regla que más fricción ahorra: tipa fuerte en los bordes y deja el interior libre.
@dataclassclass Pedido: # interior: tipos claros id: int total: Decimal
def cargar(ruta: str) -> Pedido: # borde: valida y convierte aquí datos = json.loads(Path(ruta).read_text(encoding="utf-8")) return Pedido(id=int(datos["id"]), total=Decimal(datos["total"]))Todo lo que entra del exterior —JSON, formularios, variables de entorno, argumentos— se valida una vez, en un sitio. Después, el resto del programa puede confiar en los tipos sin comprobarlos.
La trampa
Sección titulada «La trampa»Cuándo no aplica
Sección titulada «Cuándo no aplica»- En prototipos y scripts de usar y tirar, las anotaciones son ceremonia.
- En código con
**kwargsdinámicos, donde el tipo real no se conoce hasta ejecutar. - Si el equipo no ejecuta el analizador. Anotaciones sin
mypyen CI son documentación que se desactualiza. - Para validar datos externos. Eso es
pydantico validación explícita; las anotaciones no validan.
Ejercicio
Sección titulada «Ejercicio»Esta función tiene dos puntos débiles: uno que el tipado detecta (llamarla con el tipo equivocado) y otro que no puede detectar (la secuencia vacía):
def promedio(valores: list[float]) -> float: return sum(valores) / len(valores)Escribe la versión tipada correcta y explica qué dos casos hay que tratar explícitamente, y cuál de los dos resuelve el tipo y cuál el código.
Solución
from collections.abc import Sequence
def promedio(valores: Sequence[float]) -> float: if not valores: raise ValueError("promedio de una secuencia vacía") return sum(valores) / len(valores)Dos decisiones, una de cada lado:
Sequenceen lugar delist. La función sólo lee y recorre; aceptar cualquier secuencia —una tupla, unrange, unarray— es más útil y no cuesta nada. Conlistestás prometiendo más de lo que necesitas.- El vacío.
len(valores)puede ser cero, y el tipado no lo detecta:promedio([])es unSequence[float]válido ymypyno se queja. Ese caso hay que tratarlo en código (elraise), no en la anotación: Python no tiene un tipo «lista no vacía» en la biblioteca estándar.
El tercer caso, que el tipado sí detecta: llamar con promedio([1, "2"]) revienta en el sum con TypeError, y mypy lo marca en la línea de la llamada, antes de ejecutar.
Comprobación con datos de ejemplo:
print(promedio([2.0, 4.0, 9.0]))print(promedio((1.0, 2.0)))print(promedio(range(1, 5)))try: promedio([])except ValueError as error: print("error:", error)assert promedio([2.0, 4.0]) == 3.0, "media de dos valores"Referencias
Sección titulada «Referencias»- Ramalho, L. Fluent Python, 2ª ed. Capítulos 8 y 15: tipado gradual,
Protocoly varianza. - Lott, S. F. Modern Python Cookbook, 3ª ed. Capítulo 10: Type Matching and Annotations.
- PEP 484 (tipado gradual), PEP 544 (
Protocol), PEP 649 (anotaciones diferidas, 3.14). - Mediciones:
mediciones/03-09-11-llamada-tipos.py.
Capítulos relacionados
Sección titulada «Capítulos relacionados»- 09 · El protocolo de llamada:
Callablecomo tipo. - 05 · Iterables:
IterableyIteratorcomo contratos. - 04 · ABCs y Protocol (Parte IV): el protocolo como diseño, no como anotación.