Type Hints transformaram a forma como escrevemos Python. Desde sua introdução no Python 3.5 com a PEP 484, a anotação de tipos evoluiu de um recurso opcional para uma prática essencial em projetos profissionais. Neste guia completo, você vai aprender desde a sintaxe básica até os recursos mais avançados do sistema de tipos do Python.

Se você já usa Python profissionalmente ou está construindo APIs com FastAPI, dominar type hints é o próximo passo natural para escrever código mais robusto, legível e com menos bugs. A documentação oficial do FastAPI mostra como type hints são o coração da validação automática de dados.

O Que São Type Hints?

Type hints (ou anotações de tipo) são uma forma de indicar o tipo esperado de parâmetros, retornos e variáveis em Python. Eles não alteram o comportamento em tempo de execução — Python continua sendo uma linguagem de tipagem dinâmica — mas permitem que ferramentas externas como mypy, Pyright e PyCharm analisem seu código estaticamente e encontrem erros antes mesmo de você executá-lo.

def saudacao(nome: str) -> str:
    return f"Olá, {nome}!"

O mypy detectaria este erro:


resultado = saudacao(42)  # Erro: int não é str

A sintaxe é simples: dois pontos após o nome do parâmetro seguido do tipo, e uma seta -> antes do tipo de retorno. Essa convenção foi estabelecida pela PEP 484 e expandida nas versões seguintes da linguagem.

Por Que Usar Type Hints?

Os benefícios vão muito além da simples documentação. Type hints transformam a experiência de desenvolvimento de várias formas:

  • Detecção precoce de bugs: Ferramentas como mypy encontram erros de tipo que passariam despercebidos até os testes.
  • Autocomplete poderoso: IDEs como VS Code e PyCharm usam type hints para oferecer sugestões precisas.
  • Documentação viva: O tipo da função documenta a intenção do código sem necessidade de comentários extras.
  • Refatoração segura: Mudanças na estrutura de dados são propagadas automaticamente pelo verificador de tipos.
  • Menos testes necessários: A verificação estática cobre uma camada que tradicionalmente exigiria testes unitários.

Projetos que adotam type hints reportam até 40% menos bugs relacionados a tipo em produção, segundo levantamentos da comunidade. Empresas como Dropbox, Google e Instagram usam mypy em milhões de linhas de código.

Sintaxe Básica de Type Hints

Tipos Simples

Os tipos básicos do Python são usados diretamente: int, float, str, bool, bytes.

def calcular_area(raio: float) -> float:
    return 3.14159 * raio ** 2

def ativar_usuario(ativo: bool) -> str:
return "Ativo" if ativo else "Inativo"

Tipos de Coleção

Para listas, dicionários e outros tipos compostos, usamos o módulo typing. Desde o Python 3.9, graças à PEP 585, podemos usar os próprios tipos embutidos como genéricos:

from typing import Dict, List, Optional, Tuple, Union

Python 3.8 e anteriores


nomes: List[str] = ["Ana", "Bob", "Carol"]
config: Dict[str, int] = {"porta": 8080, "timeout": 30}
opcional: Optional[str] = None  # Equivalente a Union[str, None]


Python 3.9+


nomes: list[str] = ["Ana", "Bob", "Carol"]
config: dict[str, int] = {"porta": 8080, "timeout": 30}


Python 3.10+


opcional: str | None = None
retorno: int | str = 42  # Union simplificada (PEP 604)

A PEP 604 simplificou drasticamente a sintaxe de tipos union com o operador |, eliminando a necessidade de Union e Optional na maioria dos casos.

Type Aliases

Você pode criar apelidos para tipos complexos, melhorando a legibilidade:

Coordenadas = tuple[float, float]
Matriz = list[list[float]]

def distancia(p1: Coordenadas, p2: Coordenadas) -> float:
return ((p2[0] - p1[0])  2 + (p2[1] - p1[1])  2) ** 0.5

Tipagem em Funções

Parâmetros com Valores Padrão

def conectar(host: str, porta: int = 5432, timeout: float | None = None) -> bool:
    # ...
    return True

Parâmetros *args e **kwargs

def somar(*args: int) -> int:
    return sum(args)

def log_erro(**kwargs: str) -> None:
for chave, valor in kwargs.items():
print(f"{chave}: {valor}")

Callable

Para tipar funções que recebem outras funções como parâmetro:

from collections.abc import Callable

def executar(funcao: Callable[[int, int], int], a: int, b: int) -> int:
return funcao(a, b)


resultado = executar(lambda x, y: x + y, 10, 20)  # 30

Novidades do Python 3.12 e 3.13

As versões mais recentes do Python trouxeram avanços significativos no sistema de tipos. O Python 3.12 introduziu a PEP 695 com uma sintaxe mais limpa para funções e classes genéricas:

# Python 3.11 e anteriores
from typing import TypeVar
T = TypeVar("T")

def primeiro_elemento(lista: list[T]) -> T:
return lista[0]


Python 3.12+


def primeiro_elemento[T](lista: list[T]) -> T:
return lista[0]


Classes genéricas


class Pilha[T]:
def init(self) -> None:
self._itens: list[T] = []


def push(self, item: T) -> None:
    self._itens.append(item)

def pop(self) -> T:
    return self._itens.pop()

O Python 3.13 continuou refinando o ecossistema com melhorias no suporte a tipos para a biblioteca padrão. Para uma visão completa de todas as mudanças, consulte a documentação oficial do módulo typing.

Generics e TypeVar

TypeVar permite criar funções e classes que funcionam com vários tipos mantendo a segurança de tipo. É um dos pilares da programação genérica em Python.

from typing import TypeVar

T = TypeVar("T")  # Qualquer tipo
U = TypeVar("U")  # Outro tipo genérico


def emparelhar(a: T, b: U) -> tuple[T, U]:
return (a, b)


TypeVar com restrição


Numero = TypeVar("Numero", int, float)


def dobrar(valor: Numero) -> Numero:
return valor * 2

TypeVar com bound

O parâmetro bound restringe o TypeVar a subtipos de uma classe específica:

from typing import TypeVar
from collections.abc import Iterable

Iteravel = TypeVar("Iteravel", bound=Iterable)


def primeiro(seq: Iteravel) -> object:
for item in seq:
return item
raise ValueError("Sequência vazia")

Protocols: Duck Typing Estático

Protocols (PEP 544) permitem duck typing estático. Em vez de exigir uma classe específica, você define um conjunto de métodos que o objeto precisa implementar. Isso é especialmente útil para testabilidade e desacoplamento.

from typing import Protocol

class Imprimivel(Protocol):
def imprimir(self) -> str: ...


class Relatorio:
def imprimir(self) -> str:
return "Conteúdo do relatório"


class Invoice:
def imprimir(self) -> str:
return "Invoice #1234"


def gerar_saida(obj: Imprimivel) -> None:
print(obj.imprimir())


gerar_saida(Relatorio())  # OK
gerar_saida(Invoice())    # OK também

Protocols são uma alternativa mais flexível à herança tradicional. Eles permitem que você programe para interfaces sem acoplar seu código a hierarquias de classes rígidas. Se você quer entender melhor como isso se relaciona com padrões de projeto, veja nosso guia sobre {link_interno:python-decorators-guia-completo}.

TypedDict: Dicionários Tipados

TypedDict permite definir a estrutura de dicionários com tipos específicos para cada chave:

from typing import TypedDict

class Usuario(TypedDict):
nome: str
email: str
idade: int
ativo: bool


def criar_usuario(dados: Usuario) -> Usuario:
return dados


O mypy detecta se uma chave obrigatória estiver faltando


usuario = criar_usuario({
"nome": "Ana",
"email": "[email protected]",
"idade": 28,
"ativo": True
})

Você pode usar total=False para tornar todas as chaves opcionais, ou combinar com Required e NotRequired (Python 3.11+) para controle fino.

Dataclasses com Type Hints

Dataclasses (PEP 557) e type hints formam uma combinação poderosa. As anotações de tipo são usadas automaticamente pelos dataclasses para gerar métodos como __init__ e __repr__:

from dataclasses import dataclass, field

@dataclass
class Configuracao:
host: str
porta: int = 8080
timeout: float | None = None
tags: list[str] = field(default_factory=list)


config = Configuracao(host="localhost", porta=3000)
print(config)  # Configuracao(host='localhost', porta=3000, timeout=None, tags=[])

Dataclasses são amplamente usados em conjunto com FastAPI e Pydantic para modelagem de dados. Se você quer ver type hints em ação em APIs reais, confira nosso guia sobre {link_interno:fastapi-python-criar-api-restful} que mostra na prática como a tipagem estática melhora a qualidade de APIs REST.

Pydantic: Validação em Tempo de Execução

Enquanto type hints atuam em tempo de análise estática, o Pydantic leva a tipagem para o runtime. Com ele, você define modelos com type hints e ganha validação automática, serialização e documentação:

from pydantic import BaseModel, EmailStr, PositiveInt

class Usuario(BaseModel):
nome: str
email: EmailStr
idade: PositiveInt


Se os dados forem inválidos, uma exceção detalhada é lançada


usuario = Usuario(nome="Ana", email="[email protected]", idade=25)
print(usuario.model_dump())


{'nome': 'Ana', 'email': '[email protected]', 'idade': 25}

O Pydantic é a biblioteca padrão de fato para validação de dados em Python, usada por FastAPI, LangChain, SQLModel e centenas de outros frameworks.

Ferramentas do Ecossistema

Mypy

O mypy é o verificador de tipos estático mais maduro do ecossistema Python. Ele analisa seu código e aponta inconsistências sem executá-lo:

pip install mypy
mypy meu_arquivo.py --strict

Use a flag --strict para ativar todas as verificações. A documentação oficial do mypy oferece guias detalhados de configuração.

Pyright / Pylance

O Pyright é o verificador de tipos rápido da Microsoft, usado pelo VS Code via Pylance. Ele é significativamente mais rápido que o mypy em projetos grandes e oferece suporte excelente a recursos modernos de typing.

Ruff

O Ruff é um linter extremamente rápido escrito em Rust que também verifica type hints básicos e oferece autofix para anotações ausentes.

Boas Práticas com Type Hints

  • Prefira tipos genéricos embutidos (Python 3.9+): Use list[str] em vez de List[str] do typing.
  • Use | em vez de Union (Python 3.10+): int | str é mais legível que Union[int, str].
  • Evite Any quando possível: Any desativa a verificação de tipo completamente.
  • Use Never para funções que nunca retornam: Como sys.exit() ou raises incondicionais.
  • Prefira Self para retorno de métodos de instância (Python 3.11+): Garante que subclasses mantenham o tipo correto.
  • Use TypeGuard para narrowing avançado (Python 3.10+): Funções que informam ao verificador de tipos sobre o tipo exato do retorno.

Type Hints em Projetos Reais

Empresas de tecnologia de todos os portes adotaram type hints como parte essencial do desenvolvimento. O Dropbox, que mantém o mypy, possui milhões de linhas de Python tipadas estaticamente. O Instagram usa Pyre, seu próprio verificador de tipos. O Google adotou o pytype para seus projetos internos.

A Real Python possui um tutorial abrangente sobre type checking que complementa este guia com exemplos adicionais e exercícios práticos.

Conclusão

Type Hints evoluíram de um recurso experimental no Python 3.5 para uma prática fundamental no ecossistema Python moderno. Com a sintaxe simplificada das versões recentes (PEP 585, PEP 604, PEP 695), nunca foi tão fácil adicionar tipagem estática ao seu código.

Comece aos poucos: adicione type hints aos parâmetros e retornos das funções principais, configure o mypy no seu projeto e deixe que as ferramentas ajudem você a escrever código mais seguro e autodocumentado. Em pouco tempo, type hints se tornarão uma parte natural do seu fluxo de desenvolvimento.

Continue seus estudos com nosso guia completo sobre {link_interno:fastapi-python-criar-api-restful} e veja como type hints transformam a criação de APIs REST modernas.