Noções Básicas de Type Hints

9 exemplos para você começar com type hints em Python - 6 básicos e 3 intermediários.

Pré-requisitos

• Python 3.14.0 com mypy ou pyright disponíveis (uv add --dev mypy).

Exemplos Básicos

1. Anotações de Variáveis e Funções

Documente os tipos esperados em nomes e assinaturas.

name: str = "Ada"
count: int = 0
 
def greet(user: str) -> str:
    return f"Hello, {user}"

• Anotações armazenadas em __annotations__ mas não impostas em tempo de execução.
• Retorno -> None documenta que não há valor de retorno útil.
• Adicione hints gradualmente a módulos estáveis primeiro.

Relacionado: Genéricos Embutidos e de Coleção - list[int], dict[str, int]

2. Tipos de Coleção

Use genéricos embutidos para contêineres (3.9+).

users: list[str] = []
index: dict[str, int] = {}
unique: set[int] = set()

• list sem parâmetros significa lista não tipada para verificadores rigorosos.
• Prefira tipos de contêineres concretos em vez de abstratos, a menos que a API exija flexibilidade.
• O comprimento da tupla pode ser fixo: tuple[int, str].

Relacionado: Genéricos Embutidos e de Coleção - Sequence, Mapping

3. Opcional e None

Valores anuláveis usam união com None.

def find_user(user_id: int) -> dict | None:
    return None
 
email: str | None = None

• Optional[str] é equivalente a str | None (estilo mais antigo).
• Refine com if x is not None antes do uso - verificadores refinam tipos.
• Não use Optional quando None não for permitido.

Relacionado: Optional, Union & o Operador | - narrowing

4. Executando mypy

Verifique tipos estaticamente em CI.

uv run mypy src/

# Trecho de pyproject.toml
[tool.mypy]
python_version = "3.14"
strict = false
warn_return_any = true

• Comece permissivo; reforce por módulo com strict = true overrides.
• mypy lê a seção [tool.mypy] do pyproject.toml.
• Corrija erros nas fronteiras primeiro - manipuladores HTTP, adaptadores de banco de dados.

Relacionado: Configuração de mypy & pyright - configuração completa

5. Narrowing com isinstance

Combine verificações em tempo de execução com narrowing estático.

def handle(value: str | int) -> str:
    if isinstance(value, str):
        return value.upper()
    return str(value * 2)

• isinstance ajuda mypy/pyright a refinar uniões.
• match/case também refina quando os padrões são específicos de tipo.
• A validação em tempo de execução ainda é necessária em fronteiras não confiáveis (use Pydantic 2).

Relacionado: Optional, Union & o Operador | - type guards

6. Definição Tipada com Escape Hatch Any

Any opta por não verificar - use com moderação.

from typing import Any
 
def legacy_bridge(payload: Any) -> dict[str, Any]:
    assert isinstance(payload, dict)
    return payload

• Any é contagioso - retornos infectam chamadores.
• Prefira object quando qualquer valor for permitido, mas não operações arbitrárias.
• Refine Any nas bordas do sistema ao longo do tempo.

Exemplos Intermediários

7. Tipos Callable

Tipa funções de ordem superior.

from collections.abc import Callable
 
def apply(fn: Callable[[int, int], int], a: int, b: int) -> int:
    return fn(a, b)

• Callable[[ArgTypes], ReturnType] documenta a forma da função.
• ParamSpec preserva assinaturas de decoradores (avançado).
• Prefira Callable em vez de funções não tipadas em APIs públicas.

Relacionado: Overloads & Tipos Callable - ParamSpec

8. Atributos de Classe

Anote variáveis de instância e de classe.

class Counter:
    total: int = 0
 
    def __init__(self) -> None:
        self.value: int = 0

• Variável de classe anotada no corpo da classe; variáveis de instância frequentemente em __init__.
• ClassVar marca atributos que não são substituídos em instâncias.
• Dataclasses geram anotações a partir das definições de campo.

Relacionado: dataclasses - campos tipados

9. Estratégia de Tipagem Gradual

Adicione tipos módulo por módulo.

# mypackage/service.py  (tipado)
def compute(x: int) -> int:
    return x + 1
 
# mypackage/legacy.py  (não tipado por enquanto)
def legacy(): ...

• Habilite check_untyped_defs após cobertura de linha de base.
• Use # type: ignore[code] com moderação, com um comentário explicando o motivo.
• Acompanhe o progresso com relatórios de cobertura mypy por pacote.

Relacionado: Estratégia de Tipagem Gradual - plano de implantação

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.