Respuesta.

Las anotaciones de tipo (type hints) son una forma de especificar explícitamente los tipos esperados de variables, argumentos y valores de retorno de funciones. La sintaxis apareció en Python 3.5 (PEP 484). Las anotaciones son estáticas: el intérprete las ignora durante la ejecución, están destinadas a herramientas de análisis de código (mypy, Pyright, IDE).

Las anotaciones ayudan a:

• Mejorar la legibilidad y la autocontradicción del código.
• Permitir que las herramientas analicen y detecten errores de tipo antes de la ejecución.
• Ser utilizadas en autocompletado, refactorización y documentación.

Ejemplo:

def add(x: int, y: int) -> int:
    return x + y

def show(items: list[str]) -> None:
    print(', '.join(items))

Pregunta engañosa.

Pregunta común:

¿Pueden las anotaciones de tipo de alguna manera afectar el rendimiento o la corrección de la ejecución del código?

Respuesta: No, las anotaciones de tipo no afectan ni al rendimiento ni a la funcionalidad del programa en tiempo de ejecución. Son solo metadatos. Pero pueden ser utilizadas por herramientas o frameworks externos para el control y la validación de tipos (por ejemplo, en FastAPI).

Ejemplos de errores reales debido a un desconocimiento de las sutilezas del tema.

---

Historia

En el proyecto, grandes estructuras dinámicas se marcaban con tipos a través de list, dict sin especificar los elementos (por ejemplo: def f(x: list): ...). Como resultado, los analizadores estáticos no podían detectar errores de tipo, porque la anotación no aclaraba qué hay dentro.

---

Historia

Se utilizó from __future__ import annotations para soportar la evaluación pospuesta en Python 3.7, pero se olvidaron de esto en una parte del proyecto. Esto llevó a que las referencias forward causaran errores durante el análisis estático y en tiempo de ejecución al usar ciertos frameworks.

---

Historia

En un gran proyecto, se especificó incorrectamente el tipo del valor de retorno: se olvidó importar Optional, lo que resultó en un error de mypy y una serie de problemas no documentados en el IDE, que interrumpieron el autocompletado y la resaltación de errores.