Saltearse al contenido

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.

El tipado no cambia el programa: cambia lo que se puede demostrar sobre el programa antes de ejecutarlo.

def sumar(a: int, b: int) -> int:
return a + b
sumar("1", "2") # "12" — no hay error
sumar.__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
Comprobar un tipo en runtime
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.

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+
  • Protocol describe la forma que debe tener un objeto, sin obligar a heredar. Es duck typing documentado y comprobable.
  • TypedDict tipa un diccionario con claves fijas: útil para JSON y para **kwargs.
  • Literal restringe 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]) es int). En código que debe correr en 3.11, se escribe con TypeVar("T") de typing.

La regla que más fricción ahorra: tipa fuerte en los bordes y deja el interior libre.

@dataclass
class 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.

  • En prototipos y scripts de usar y tirar, las anotaciones son ceremonia.
  • En código con **kwargs dinámicos, donde el tipo real no se conoce hasta ejecutar.
  • Si el equipo no ejecuta el analizador. Anotaciones sin mypy en CI son documentación que se desactualiza.
  • Para validar datos externos. Eso es pydantic o validación explícita; las anotaciones no validan.

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:

  1. Sequence en lugar de list. La función sólo lee y recorre; aceptar cualquier secuencia —una tupla, un range, un array— es más útil y no cuesta nada. Con list estás prometiendo más de lo que necesitas.
  2. El vacío. len(valores) puede ser cero, y el tipado no lo detecta: promedio([]) es un Sequence[float] válido y mypy no se queja. Ese caso hay que tratarlo en código (el raise), 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.

  • Ramalho, L. Fluent Python, 2ª ed. Capítulos 8 y 15: tipado gradual, Protocol y 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.
  • 09 · El protocolo de llamada: Callable como tipo.
  • 05 · Iterables: Iterable y Iterator como contratos.
  • 04 · ABCs y Protocol (Parte IV): el protocolo como diseño, no como anotación.