Configuración de mypy y pyright

Los verificadores de tipos estáticos detectan errores antes de la ejecución. Configure mypy o pyright en pyproject.toml, ejecútelos en CI junto con ruff 0.9+ y ajuste la estrictez a medida que crece la cobertura.

Receta

# 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

Cuándo usar esto:

• Inicio de un nuevo servicio Python
• Refuerzo del pipeline de CI
• Monorepo con paquetes mixtos tipados/no tipados
• Comparación de mypy vs pyright en casos límite

Ejemplo Funcional

# Extracto de pyproject.toml para una aplicación con estructura 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

Lo que esto demuestra:

• packages + explicit_package_bases para el descubrimiento de mypy en la estructura src
• Las anulaciones por módulo relajan las pruebas mientras la aplicación se mantiene tipada
• El modo standard de pyright es más estricto que basic
• CI ejecuta ambos verificadores cuando el equipo desea la máxima señal

Profundización

Cómo Funciona

• mypy - Verificador nominal incremental; potentes plugins de ecosistema (django, pydantic).
• pyright - Rápido; impulsa Pylance; bueno para repositorios grandes e inferencia estricta.
• Stubs - Paquetes types-* en PyPI para bibliotecas de terceros no tipadas.
• py.typed - Marcador PEP 561 en paquetes instalados que exportan tipos.
• ruff - Linter/formateador; separado de la verificación de tipos (aunque ruff tiene reglas limitadas conscientes de tipos).

Progresión de Estrictez

Notas de Python

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

Errores Comunes

• mypy no encuentra importaciones - Estructura src sin configuración packages. Solución: mypy_path o configuración de paquete + instalación editable.
• pyright no encuentra stubs - Informa tipos desconocidos. Solución: Instalar stubs o reportMissingTypeStubs = false temporalmente.
• Abuso de # type: ignore - Oculta errores reales para siempre. Solución: warn_unused_ignores y limpieza periódica.
• Verificar site-packages de venv - Lento y ruidoso. Solución: Limitar include/packages a su código.
• Resultados divergentes de mypy/pyright - Elegir el verificador principal; usar el secundario como asesor hasta que se alineen.

Alternativas

Preguntas Frecuentes

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

Relacionado

• Estrategia de Tipado Gradual - plan de implementación
• Conceptos Básicos de Type Hints - introducción a las anotaciones
• mypy y pyright en CI - hermano de la sección de linting
• Guía Rápida de Entornos Virtuales - dependencias de desarrollo uv

Versiones de pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 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+ y uv 0.6+.