El módulo 7 terminó con una tienda que ya no se cae: se explica. Pero para explicarse, Papyrus dependía de docstrings, de guard clauses y de tu memoria: ¿vender() devuelve el importe o el Libro? ¿buscar_libro() puede devolver None? Hasta ahora la respuesta vivía en tu cabeza o en un comentario. Las anotaciones de tipos (type hints) escriben esos contratos directamente en la firma de la función, donde el editor, las herramientas y el próximo lector — probablemente tú dentro de tres meses — pueden verlos. En esta lección también saldamos una deuda concreta: en la lección 05-06 dijimos que las anotaciones de las dataclasses "son type hints que se estudian en el módulo 8". Ese momento es ahora.

1. Qué son los type hints y, sobre todo, qué NO hacen
2. Sintaxis básica: variables, parámetros y valor de retorno
3. Tipos genéricos modernos: list[Libro], dict[str, Libro], tuple, set
4. | None y Optional: el contrato de buscar_libro()
5. Union con |: cuando algo puede ser varias cosas
6. Anotar almacen.py: las firmas reales de Papyrus
7. TypedDict: dar forma a las filas de CSV y JSON
8. mypy: el verificador externo
9. Beneficios reales y cuándo relajarse

Una anotación de tipo es una etiqueta que declara qué tipo de valor se espera en una variable, un parámetro o un retorno:

• precio: float — el parámetro debería ser un float.
• -> float — la función devuelve un float.

Y ahora lo más importante de toda la lección: Python no comprueba las anotaciones en tiempo de ejecución. Este código se ejecuta sin protestar:

El error que verás es el mismo TypeError de siempre, producido al intentar multiplicar; la anotación ni lo provocó ni lo evitó. Las anotaciones son documentación estructurada: Python las guarda (en __annotations__) pero las ignora al ejecutar. Quien las aprovecha es el ecosistema: tu editor para autocompletar, y verificadores externos como mypy para detectar errores antes de ejecutar. Compáralo con lo que hacía el módulo 7:

No son alternativas: son capas. Los type hints detectan el error en tu pantalla mientras escribes; las guard clauses lo detienen si a pesar de todo llega en ejecución.

En variables locales con valor evidente (unidades = 2) la anotación suele sobrar: el tipo se infiere. Donde brilla es en constantes de módulo, en atributos y en variables que se inicializan "vacías":

Fíjate en que el valor por defecto convive con la anotación: socio: bool = False. Una función que no devuelve nada se anota con -> None:

Las colecciones se anotan indicando qué contienen, con corchetes. Desde Python 3.9 se usan los tipos integrados directamente (verás List y Dict importados de typing en código antiguo; hoy ya no hacen falta):

Y aquí se salda la promesa de 05-06: en la dataclass Libro, las líneas titulo: str, precio: float, stock: int = 0 son exactamente esto — anotaciones de tipo. @dataclass las lee de __annotations__ para generar __init__ y compañía. Es el único lugar de Python donde las anotaciones tienen un efecto práctico directo... y aun así, en ejecución nadie verifica que precio sea de verdad un float: por eso Libro necesita su __post_init__.

En el módulo 7 diseñamos dos funciones hermanas con contratos distintos: buscar_libro() devuelve el libro o None (la ausencia es un caso normal), y obtener_libro() devuelve el libro o lanza LibroNoEncontradoError. Ese contrato, que entonces defendíamos en la docstring, ahora se escribe en la firma:

Libro | None se lee "un Libro o None". Es la forma moderna (Python 3.10+) de Optional[Libro], que aún verás en muchísimo código:

Son equivalentes. La ventaja práctica: cuando escribes buscar_libro(catalogo, "Hamlet").precio_final(), un verificador te avisa de que el resultado podría ser None y que None no tiene precio_final() — el clásico AttributeError de las 20:05 con la tienda cerrada, detectado antes de ejecutar.

El mismo operador sirve para cualquier unión de tipos, no solo con None:

Úsalo con moderación: una función que devuelve str | float | bool | None está pidiendo a gritos un rediseño. Los contratos claros de M7 (una función, un tipo de resultado, o una excepción) siguen siendo la mejor guía.

Así quedan las cabeceras de almacen.py con sus contratos a la vista. Compara cada firma con lo que la función ya hacía en M6 y M7 — no cambia ni una línea de lógica:

Observa cuánta historia del curso cabe en una firma: obtener_libro no anota Libro | None porque su contrato es lanzar, no devolver None — la excepción no forma parte de la anotación de retorno (se documenta en la docstring). Y vender devuelve float: el importe, no el libro. Dudas que en M7 resolvías releyendo el cuerpo, ahora se responden sin abrir la función.

csv.DictReader (M6) devuelve diccionarios, y dict[str, str] dice poco: ¿qué claves? TypedDict declara la forma exacta:

Con esto, fila["importr"] (errata incluida) deja de ser una bomba de relojería KeyError: mypy la marca al instante. Es una pincelada — suficiente para las filas de ventas.csv y los objetos de catalogo.json; no necesitas más por ahora.

Si Python no comprueba las anotaciones, algo tiene que hacerlo. Ese algo es mypy, que se instala en el venv del proyecto como cualquier paquete (M1):

Ejemplo real del bug que caza. Este código se ejecuta la mayoría de las veces... hasta que el libro no existe:

mypy no ejecutó nada: leyó las firmas y dedujo que ese AttributeError era posible. El arreglo es el patrón LBYL/EAFP de 07-01, y ahora la herramienta te obliga a elegirlo conscientemente:

Tras el if, mypy estrecha el tipo: sabe que libro ya es Libro. A esto se le llama narrowing y es la razón por la que anotar | None compensa siempre.

Beneficios: documentación viva que no se desactualiza como los comentarios (si cambias la función y no la firma, mypy protesta); autocompletado preciso en el editor (escribe libro. y aparecen precio_final y hay_stock); y bugs detectados antes de ejecutar, como el None de arriba.

Cuándo relajarse: en un script de veinte líneas para renombrar los archivos de copias/, anotar cada variable es burocracia. La regla práctica: anota siempre las firmas públicas de tus módulos (almacen.py, modelos.py, errores.py — sus atributos como solicitado: int y disponible: int también agradecen tipos); relájate en scripts desechables y variables locales obvias. Los type hints son graduales por diseño: puedes anotar un módulo hoy y otro el mes que viene.

• Creer que las anotaciones validan: def vender(unidades: int) no impide vender("dos"). Para rechazar datos en ejecución siguen haciendo falta las guard clauses de 07-03. Los hints avisan antes; los raise protegen durante.
• Olvidar el | None en funciones que pueden no encontrar: si buscar_libro se anota -> Libro, mientes al lector y a mypy, que dejará pasar el AttributeError. La anotación debe contar toda la verdad.
• list a secas en vez de list[Libro]: es legal pero pierde casi todo el valor — el editor no sabrá autocompletar los elementos.
• Importar List/Optional de typing por inercia: en Python moderno (3.10+), list[...] y X | None son la forma preferida. Reconoce la vieja al leerla; escribe la nueva.
• Consejo: ejecuta mypy como parte de tu rutina, igual que miras papyrus.log. Un error de mypy es un bug que no llegó a producción.
• Consejo: cuando una firma anotada te quede larguísima o llena de |, no pelees con la sintaxis — suele ser la firma la que pide simplificar la función.

1. Anota completamente esta función de Papyrus (parámetros y retorno), sabiendo que devuelve el título del libro más caro del catálogo o None si el catálogo está vacío:

   def mas_caro(catalogo):
       if not catalogo:
           return None
       return max(catalogo.values(), key=lambda l: l.precio).titulo
   

2. Define un TypedDict llamado FilaCatalogo para las filas del CSV del catálogo (claves titulo, precio, stock, todas str porque vienen de DictReader) y anota la función fila_a_libro(fila) que convierte una fila en un Libro (puede lanzar ValueError si el precio no es numérico — recuerda: eso va en la docstring, no en el ->).

3. Este código pasa desapercibido hasta que Omar pide un título agotado. ¿Qué error señalaría mypy y cómo lo corregirías usando el contrato de errores.py?

   def cobrar(catalogo: dict[str, Libro], titulo: str) -> float:
       libro = buscar_libro(catalogo, titulo)
       if not libro.hay_stock():
           raise StockInsuficienteError(titulo, 1, 0)
       return libro.precio_final()
   

1. def mas_caro(catalogo: dict[str, Libro]) -> str | None:
       if not catalogo:
           return None
       return max(catalogo.values(), key=lambda l: l.precio).titulo
   

   El -> str | None es obligatorio: hay un camino que devuelve None. Anotar solo -> str sería mentir.

2. from typing import TypedDict
   
   class FilaCatalogo(TypedDict):
       titulo: str
       precio: str
       stock: str
   
   def fila_a_libro(fila: FilaCatalogo) -> Libro:
       """Convierte una fila de CSV en Libro. Lanza ValueError si precio/stock no son numéricos."""
       return Libro(fila["titulo"], float(fila["precio"]), int(fila["stock"]))
   

   Las conversiones float()/int() son las mismas que cierre_de_caja protege con su try mínimo (07-02); la excepción posible se documenta en la docstring.

3. mypy señala Item "None" of "Libro | None" has no attribute "hay_stock": buscar_libro puede devolver None y None.hay_stock() explotaría. Dos arreglos coherentes con M7: comprobar if libro is None: raise LibroNoEncontradoError(titulo) antes de usarlo, o directamente llamar a obtener_libro(catalogo, titulo), cuya firma -> Libro ya garantiza (lanzando si hace falta) que hay libro. La segunda es mejor: reutiliza el contrato existente.

Los type hints escriben en las firmas los contratos que el módulo 7 defendía a mano: buscar_libro() -> Libro | None cuenta la verdad completa, vender() -> float despeja la duda del importe, y las anotaciones de la dataclass Libro — la promesa pendiente de 05-06 — por fin tienen nombre y apellidos. Python no las comprueba en ejecución; mypy y tu editor las convierten en una red que caza bugs antes de que Júlia o Omar los sufran. Con los contratos ya visibles, el siguiente paso ataca otra repetición: en Papyrus queremos cronometrar cierre_de_caja, auditar cada venta en el log de M7 y reintentar operaciones frágiles — sin copiar y pegar el mismo código alrededor de cada función. Eso es exactamente lo que resuelven los decoradores, y son la próxima lección.