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

Estágio	flags do mypy
1	`warn_return_any`
2	`check_untyped_defs`
3	`disallow_untyped_defs` por pacote
4	`strict = true` em novos módulos

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

Alternativa	Usar Quando	Não Usar Quando
apenas pyright	Equipe VS Code/Pylance	Plugins específicos do mypy necessários
apenas mypy	Plugins Django/mypy	Deseja paridade com Pylance
pytype	Pilhas legadas do Google	Greenfield
nenhum verificador	Script descartável	Serviços de produção

FAQs

mypy ou pyright?

Muitas equipes executam mypy em CI e pyright em IDE via Pylance - ou escolhem um portão de CI para começar.

onde vive a configuração?

pyproject.toml [tool.mypy] e [tool.pyright] preferidos em relação a arquivos ini dispersos.

rigor desde o primeiro dia?

Geralmente muito barulhento em brownfield - reforce módulo por módulo com overrides.

formato do type ignore?

# type: ignore[arg-type] códigos específicos - exigido no mypy moderno com show_error_codes.

plugin pydantic mypy?

O plugin Pydantic 2 melhora a tipagem de modelos - ative na configuração do mypy para projetos FastAPI.

hook pre-commit?

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

pacotes monorepo?

Separe overrides de mypy por caminho de pacote ou use mypy -p package na matriz de CI.

pin python_version?

Corresponda a requires-python e à matriz de CI - 3.14 para este cookbook.

ruff substitui mypy?

Não - ruff formata/linta de forma complementar; a verificação de tipos continua sendo trabalho do mypy/pyright.

falha na CI por avisos?

Comece apenas com erros; promova avisos para erros à medida que a dívida diminui.

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+.

Configuração de mypy & pyright

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

Estágio	flags do mypy
1	`warn_return_any`
2	`check_untyped_defs`
3	`disallow_untyped_defs` por pacote
4	`strict = true` em novos módulos

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

Alternativa	Usar Quando	Não Usar Quando
apenas pyright	Equipe VS Code/Pylance	Plugins específicos do mypy necessários
apenas mypy	Plugins Django/mypy	Deseja paridade com Pylance
pytype	Pilhas legadas do Google	Greenfield
nenhum verificador	Script descartável	Serviços de produção

FAQs

mypy ou pyright?

Muitas equipes executam mypy em CI e pyright em IDE via Pylance - ou escolhem um portão de CI para começar.

onde vive a configuração?

pyproject.toml [tool.mypy] e [tool.pyright] preferidos em relação a arquivos ini dispersos.

rigor desde o primeiro dia?

Geralmente muito barulhento em brownfield - reforce módulo por módulo com overrides.

formato do type ignore?

# type: ignore[arg-type] códigos específicos - exigido no mypy moderno com show_error_codes.

plugin pydantic mypy?

O plugin Pydantic 2 melhora a tipagem de modelos - ative na configuração do mypy para projetos FastAPI.

hook pre-commit?

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

pacotes monorepo?

Separe overrides de mypy por caminho de pacote ou use mypy -p package na matriz de CI.

pin python_version?

Corresponda a requires-python e à matriz de CI - 3.14 para este cookbook.

ruff substitui mypy?

Não - ruff formata/linta de forma complementar; a verificação de tipos continua sendo trabalho do mypy/pyright.

falha na CI por avisos?

Comece apenas com erros; promova avisos para erros à medida que a dívida diminui.

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+.

Configuração de mypy & pyright

Buscar na documentação

Configuração de mypy & pyright