typing.overload descreve várias assinaturas de uma mesma função para o verificador estático. Ele é útil quando o tipo retornado depende do tipo ou da combinação dos argumentos e uma união simples perderia essa relação.
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 ")As declarações com @overload terminam em ... e vêm imediatamente antes de uma implementação concreta. Em runtime, a última função trata todos os casos; por isso ela ainda precisa validar entradas e manter comportamento coerente com cada assinatura publicada.
Boas práticas
Ordene assinaturas específicas antes das amplas e evite sobreposições impossíveis de distinguir. Teste também a implementação, pois o type checker não prova a lógica em runtime. Se um TypeVar expressar a relação de entrada e saída de forma mais curta, prefira-o; overloads extensas elevam o custo de manutenção.
Revise o guia de type hints e use mypy para conferir as assinaturas no projeto.
A documentação oficial de typing.overload, consultada em 22 de julho de 2026, detalha a API e seus limites.