Configuração de mypy & pyright

Verificadores de tipo estático capturam bugs antes da execução. Configure mypy ou pyright em pyproject.toml, execute em CI junto com ruff 0.9+, e reforce o rigor à medida que a cobertura aumenta.

Receita

# pyproject.toml
[tool.mypy]
python_version = "3.14"
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = false
 
[tool.pyright]
pythonVersion = "3.14"
typeCheckingMode = "basic"

uv run mypy src/
uv run pyright

Quando usar isso:

• Inicialização de um novo serviço Python
• Endurecimento de pipeline de CI
• Monorepo com pacotes tipados/não tipados mistos
• Comparando mypy vs pyright em casos extremos

Exemplo de Trabalho

# Trecho de pyproject.toml para um app com layout src
[project]
name = "demo-app"
requires-python = ">=3.14"
 
[dependency-groups]
dev = ["mypy>=1.14", "pyright>=1.1.390", "ruff>=0.9"]
 
[tool.mypy]
python_version = "3.14"
packages = ["demo_app"]
namespace_packages = true
explicit_package_bases = true
warn_redundant_casts = true
warn_unused_ignores = true
pretty = true
 
[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false
 
[tool.pyright]
include = ["src"]
exclude = ["**/__pycache__", "tests/fixtures"]
pythonVersion = "3.14"
typeCheckingMode = "standard"
reportMissingImports = true

# .github/workflows/types.yml
name: types
on: [pull_request]
jobs:
  mypy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --dev
      - run: uv run mypy
      - run: uv run pyright

O que isso demonstra:

• packages + explicit_package_bases para descoberta mypy de layout src
• Overrides por módulo relaxam testes enquanto o app permanece tipado
• Modo standard do pyright é mais rigoroso que basic
• CI executa ambos os verificadores quando a equipe deseja sinal máximo

Mergulho Profundo

Como Funciona

• mypy - Verificador nominal incremental; fortes plugins de ecossistema (django, pydantic).
• pyright - Rápido; alimenta Pylance; bom para repositórios grandes e inferência rigorosa.
• Stubs - Pacotes types-* no PyPI para bibliotecas de terceiros não tipadas.
• py.typed - Marcador PEP 561 em pacotes instalados que exportam tipos.
• ruff - Linter/formatador; separado da verificação de tipos (embora ruff tenha regras limitadas cientes de tipos).

Progressão de Rigor

Notas Python

# instalar stubs para requests
uv add --dev types-requests
 
# mypy arquivo único
uv run mypy src/demo_app/main.py --show-error-codes

Armadilhas

• mypy não encontra imports - Layout src sem configuração packages. Correção: mypy_path ou configuração de pacote + instalação editável.
• pyright com stubs ausentes - Relata tipos desconhecidos. Correção: Instale stubs ou reportMissingTypeStubs = false temporariamente.
• Abuso de # type: ignore - Esconde erros reais para sempre. Correção: warn_unused_ignores e limpeza periódica.
• Verificando site-packages do venv - Lento e barulhento. Correção: Escopo include/packages para seu código.
• Resultados divergentes de mypy/pyright - Escolha o portão primário; use o secundário como consultivo até que estejam alinhados.

Alternativas

FAQs

- repo: local
  hooks:
    - id: mypy
      name: mypy
      entry: uv run mypy
      language: system
      types: [python]

Relacionado

• Estratégia de Tipagem Gradual - plano de implantação
• Noções Básicas de Type Hints - introdução à anotação
• mypy e pyright em CI - irmão da seção de lint
• Guia Rápido de Ambientes Virtuais - dependências de desenvolvimento uv

Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.