Type hints — Deja tu intención en el código con : int y -> str

Este artículo cubre los type hints — una herramienta para dejar dentro del código la intención de «qué va aquí». Introducidos en Python 3.5, han ganado expresividad con cada release.

El problema de «¿qué tipo es?» en un lenguaje dinámico

Python es un lenguaje de tipado dinámico. Escribe value = 10 y es int; escribe value = "HELLO" y el mismo nombre ahora es str. La misma variable puede cambiar de tipo en cualquier momento — eso es flexibilidad. La desventaja es que a medida que tu base de código crece o un equipo empieza a tocarla, «¿qué guarda esta variable?» / «¿qué devuelve esta función?» se vuelve incontestable solo desde el código.

Los type hints dejan esa información como anotaciones. No cambian el comportamiento en tiempo de ejecución. Lo que hacen es dar al lector humano una pista fuerte y dejar que IDEs y analizadores estáticos atrapen errores de tipo por adelantado.

Anotando firmas de función

Las firmas de función son el escenario principal para los type hints. Anota argumentos como name: type (dos puntos y luego el tipo tras el nombre) y el tipo de retorno como -> type (flecha y luego el tipo al final de la línea def).

# ❌ sin hints — la firma no te dice qué pasar
def calc_tax(price, rate):
    return int(price * (1 + rate))


# ✅ con hints — «int entra, int sale» queda obvio
def calc_tax(price: int, rate: float) -> int:
    return int(price * (1 + rate))


print(calc_tax(price=1000, rate=0.1))   # 1100

Añade type hints de argumento y de retorno a calc_tax, el calculador de impuestos estilo e-commerce.

① En def calc_tax(price, rate):, añade los hints price: int y rate: float.

② Añade -> int antes de los : para declarar el tipo de retorno.

③ Mantén el cuerpo como return int(price * (1 + rate)).

④ Verifica con print(calc_tax(price=1000, rate=0.1)) (esperado 1100).

(Si tu código se ejecuta correctamente, aparecerá la explicación.)

Anotaciones de variables — cuándo escribirlas y cuándo no

Los type hints también funcionan en variables — misma forma: name: type = value. Pero las anotaciones de variables se vuelven ruidosas rápido si abusas de ellas, y el ruido reduce la legibilidad.

# ❌ ruidoso — el valor ya te dice el tipo
name: str = "Ana"
age:  int = 30

# ✅ vale anotar — contenedor vacío, init diferida o tipo poco claro
results: list = []                       # lista vacía, se hará append más tarde
cache:   dict = {}                       # puede que quieras detallar el tipo del valor luego
user_id: int  = fetch_id_from_session()  # hace explícito el tipo esperado del sitio de llamada

En la duda: «funciones siempre, variables con cuentagotas»

En proyectos reales, anota siempre las firmas de funciones y métodos, pero anota las variables solo cuando el tipo no sea obvio. age = 30 no necesita : int — añadirlo es solo ruido.

Los type hints no se aplican en tiempo de ejecución

Los type hints son solo pistas. Python no los verifica ni los aplica en tiempo de ejecución. Una función declarada def f(x: int) acepta felizmente f("abc") — la función corre como siempre. Solo más tarde, cuando un cálculo en lo profundo del cuerpo falla por la incompatibilidad de tipo, ves un TypeError o similar — y eso es un error en tiempo de ejecución del cálculo, no del hint en sí.

Entonces, ¿para qué molestarse? Porque antes de que la función corra siquiera, los editores y analizadores estáticos pueden detectar incompatibilidades de tipo. Pylance de VS Code, PyCharm, mypy, pyright — todos leen tus hints y subrayan errores en rojo, atrapando bugs antes de la ejecución.

Los ejecutores de Python en navegador no muestran avisos del IDE

La consola de esta página solo ejecuta tu código — no tiene una facilidad de verificación estática de tipos como tiene VS Code. Así que escribir o violar type hints nunca produce subrayados rojos ni avisos previos a la ejecución aquí. El beneficio real de los type hints — la red de seguridad de los avisos del editor antes de ejecutar — solo aparece localmente con VS Code, PyCharm, etc.

Añade type hints a ambos una clase User y una función describe_user que la consume.

① Define class User: con __init__(self, name: str, age: int) asignando self.name = name y self.age = age (anota también los argumentos del constructor).

② Añade un método de instancia greet(self) -> str que devuelve f"Hola, {self.name}" (no olvides la anotación de retorno).

③ Fuera de la clase, define describe_user(user: User) -> str que toma una instancia de User y devuelve f"{user.name} ({user.age})".

④ Crea user = User("Ana", 30) y verifica con print(user.greet()) y print(describe_user(user)).

Tres lugares donde rinden los type hints