Type Hints

O que são type hints?

Type hints são etiquetas opcionais que você coloca no código para dizer qual tipo uma variável ou função espera. É como rotular uma caixa: "aqui vai texto", "aqui vai número".

O ponto mais importante: type hints não mudam como o programa funciona. Python continua dinâmico. As anotações servem para você, para sua IDE e para ferramentas como o mypy.

Sintaxe básica em variáveis

A sintaxe é simples: variável: tipo = valor. O tipo vem depois dos dois-pontos:

# Sem type hints
nome = "Ana"
idade = 25

# Com type hints
nome: str = "Ana"
idade: int = 25
altura: float = 1.75
ativo: bool = True
resultado: None = None

Funciona igualzinho com ou sem a anotação. A diferença e que sua IDE agora sabe o tipo é te ajuda com autocomplete.

Em funções -- parâmetros e retorno

Type hints brilham de verdade em funções. Você anota os parâmetros é o retorno com ->:

def saudação(nome: str, idade: int) -> str:
    return f"Olá, {nome}! Você tem {idade} anos."

print(saudação("Ana", 22))
# → Olá, Ana! Você tem 22 anos.

Com valor padrão, o hint vem antes do =:

def configurar(host: str = "localhost", porta: int = 8080) -> str:
    return f"{host}:{porta}"

print(configurar())  # → localhost:8080

Função que não retorna nada usa -> None:

def exibir(texto: str) -> None:
    print(texto)

Type hints são ignorados na execução

Isso é importante: o Python não impede você de passar o tipo errado. Ele roda normalmente:

idade: int = "vinte e cinco"  # anotou int, mas e str
print(idade)  # → vinte e cinco (funciona!)

nome: str = 42  # anotou str, mas e int
print(nome)     # → 42 (funciona!)

Tipos para colecoes (Python 3.9+)

A partir do Python 3.9, você pode usar os tipos de colecoes diretamente:

nomes: list[str] = ["Ana", "Carlos", "Maria"]
idades: dict[str, int] = {"Ana": 25, "Carlos": 30}
coordenadas: tuple[float, float] = (23.5, -46.6)
ids_unicos: set[int] = {1, 2, 3, 4}

Tipo	Significado	Exemplo
list[str]	Lista de strings	["a", "b"]
dict[str, int]	Dict com chave str e valor int	{"x": 1}
tuple[int, int]	Tupla com 2 inteiros	(1, 2)
set[int]	Conjunto de inteiros	{1, 2, 3}

Tipo opcional -- pode ser None (Python 3.10+)

Quando um valor pode ser de um tipo ou None, use |:

nome: str | None = None

def buscar_usuario(id: int) -> str | None:
    if id == 1:
        return "Ana"
    return None

resultado = buscar_usuario(1)
print(resultado)  # → Ana

resultado = buscar_usuario(99)
print(resultado)  # → None

Verificacao com mypy

O mypy é uma ferramenta que analisa seu código e encontra erros de tipo sem precisar rodar o programa:

def saudação(nome: str) -> str:
    return f"Olá, {nome}!"

resultado: int = saudação("Ana")  # mypy aponta erro aqui

mypy verificar.py
# → error: Incompatible types in assignment

Exemplo prático: cadastro tipado

def criar_perfil(
    nome: str,
    idade: int,
    email: str,
    ativo: bool = True
) -> dict[str, str | int | bool]:
    return {
        "nome": nome,
        "idade": idade,
        "email": email,
        "ativo": ativo
    }

perfil = criar_perfil("Ana", 22, "[email protected]")
print(perfil)
# → {'nome': 'Ana', 'idade': 22, 'email': '[email protected]', 'ativo': True}

Cada parâmetro tem seu tipo anotado. O retorno mostra que o dicionario pode ter valores str, int ou bool. Quem ler a função sabe exatamente o que ela espera.

Referências

• typing -- Support for type hints -- documentação oficial do módulo typing
• Python Type Checking Guide -- guia completo no Real Python
• mypy Documentation -- documentação oficial do mypy