Aprende Python desde cero

Los type hints son anotaciones que documentan qué tipos esperan tus funciones y variables. Python no los impone al ejecutar — pero editores y herramientas como mypy o pyright los usan para cazar errores ANTES de que corran.

Anotar funciones

def promedio(numeros: list[float]) -> float:
    return sum(numeros) / len(numeros)

def saludar(nombre: str) -> str:
    return f"Hola, {nombre}"

def avisar(mensaje: str, veces: int = 1) -> None:   # None: no devuelve nada
    for _ in range(veces):
        print(mensaje)

La sintaxis: parametro: tipo y -> tipo para el retorno.

Anotar variables

edad: int = 25
nombres: list[str] = ["Ana", "Luis"]
config: dict[str, int] = {"timeout": 30}

Sobre todo útil donde el tipo no se deduce fácil: variables vacías, datos de APIs, parámetros de callbacks.

La información clave: los hints NO se imponen en runtime

def suma(a: int, b: int) -> int:
    return a + b

print(suma("ab", "cd"))   # "abcd" ← ¡corre sin error!

Python ignora las anotaciones al ejecutar. Un hint es un contrato documentado que verifican herramientas estáticas, no un guardia en runtime. Si quieres validación en ejecución, usa librerías como pydantic.

Tipos modernos (Python 3.10+)

# Un tipo u otro: la barra |
def procesar(id_usuario: int | str) -> None: ...

# Opcional: puede ser None
def buscar(nombre: str) -> dict | None:
    return {"id": 1} if nombre == "ana" else None

# Secuencias que no modificas: usa abstracciones
def total(valores: list[int]) -> int: ...
def mirar(datos: dict[str, str]) -> None: ...

int | None es la forma moderna de Optional[int]
list[int], dict[str, int] funcionan directo desde Python 3.9 (antes: List[int] desde typing)

Type aliases: nombres para tipos complejos

Puntaje = dict[str, int]

def ranking(valores: Puntaje) -> list[str]: ...

¿Qué gano de verdad?

def enviar(destinatario, asunto):     # ¿str? ¿objeto Usuario? ¿una lista?
    ...

def enviar(destinatario: str, asunto: str) -> bool:   # sin dudas
    ...

Documentación viva: el hint nunca queda desactualizado (el checker lo verifica)
Autocompletado real en tu editor
Errores antes de ejecutar: pasar un str donde se espera list se detecta en el editor
Refactors seguros: cambia un tipo y el checker te lista todo lo afectado

Resumen

param: tipo y -> tipo documentan el contrato de la función
Los hints no se verifican en runtime — mypy/pyright lo hacen estáticamente
X | None para opcional; list[int] y dict[str, X] para colecciones
Los type aliases dan nombre a tipos complejos
Es la inversión más barata en calidad de código: anotar cuesta poco y paga mucho

Type hints