typing.overload en Python: Retornos Precisos

typing.overload describe varias firmas de una función para el verificador estático. Es útil cuando el retorno depende del tipo o combinación de argumentos y una unión simple perdería esa relación.

from typing import overload

@overload
def normalizar(valor: str) -> str: ...
@overload
def normalizar(valor: bytes) -> bytes: ...

def normalizar(valor: str | bytes) -> str | bytes:
    return valor.strip().lower()

texto = normalizar("  Python ")
dados = normalizar(b"  API ")

Las declaraciones con @overload terminan en ... y preceden a una implementación concreta. En runtime, la función final atiende todos los casos, por lo que debe validar entradas y cumplir cada firma publicada.

Buenas prácticas

Ordena firmas específicas antes que las amplias y evita solapamientos imposibles de distinguir. Prueba la implementación, porque el type checker no demuestra la lógica en runtime. Prefiere TypeVar si expresa la relación de forma más breve; demasiados overloads aumentan el mantenimiento.

Repasa la guía de type hints y usa mypy para comprobar las firmas.

La documentación oficial de typing.overload, consultada el 22 de julio de 2026, detalla la API y sus límites.