Guía Pyright: Comprobación rápida de tipos estáticos para código Python

Las sugerencias de tipos facilitan la comprensión y el mantenimiento del código Python. Pero aquí está el problema: las sugerencias por sí solas no detectan los errores. Necesitas un verificador de tipos para comprobar que tu código sigue realmente los tipos que has declarado.

He utilizado tanto Mypy como Pyright en producción. La ventaja de Pyright en cuanto a velocidad es más evidente durante el desarrollo. Los errores tipográficos aparecen mientras escribes, en lugar de después de guardar. En bases de código grandes, este ciclo de retroalimentación más rápido marca una diferencia real.

Este tutorial cubre todo lo que necesitas para empezar a utilizar Pyright de forma eficaz. Te mostraré cómo instalarlo, configurarlo para tu proyecto e integrarlo con VS Code. También voy a explicar las diferencias entre Pyright y Mypy.

¿Qué es Pyright?

Pyright es un verificador de tipos estáticos para Python desarrollado por Microsoft. Lee tu código, analiza las anotaciones de tipos e informa de los errores cuando los tipos no coinciden. A diferencia de las comprobaciones en tiempo de ejecución, que detectan los errores cuando se ejecuta el código, el análisis estático los detecta antes de ejecutar nada.

Aunque la mayoría de las herramientas de Python están escritas en Python, Pyright está escrito en TypeScript y se ejecuta en Node.js. Una elección extraña para una herramienta de Python, ¿verdad? Pero esa es la razón por la que Pyright es tan rápido. El motor JavaScript V8 se ejecuta mucho más rápido que CPython.

Te encontrarás con Pyright de dos maneras. Puedes ejecutarlo como una herramienta de línea de comandos en canalizaciones CI/CD para detectar errores de tipo antes de realizar fusiones. O quizá ya lo estés utilizando sin saberlo. Es la base de Pylance, la extensión Python de Microsoft para VS Code. ¿Esos garabatos rojos debajo de los errores tipográficos? Ese es Pyright trabajando entre bastidores.

La herramienta se suministra con stubs de tipos agrupados para la biblioteca estándar de Python y paquetes comunes. No es necesario instalar nada adicional para comprobar el código que utiliza os, json o typing. Para los paquetes de terceros, Pyright utiliza stubs mantenidos por la comunidad desde typeshed o stubs específicos del paquete que tú instalas por separado.

Cómo instalar Pyright

Ahora vamos a ejecutar Pyright en tu sistema. Tienes dos opciones de instalación: npm (el enfoque nativo) o pip (el envoltorio de Python).

Instalación de Pyright con npm

La instalación recomendada utiliza npm porque Pyright se ejecuta en Node.js. Necesitarás Node.js versión 14.0.0 o superior.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyright

Utilizo la instalación global para comprobaciones rápidas y la instalación local para proyectos en los que quiero fijar la versión. El enfoque npx es útil para casos puntuales sin añadir nada a tus paquetes globales.

Instalación de Pyright mediante el envoltorio de Python

Si tu equipo trabaja exclusivamente con Python y no desea incluir Node.js en la cadena de herramientas, existe un envoltorio PyPI:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]

El envoltorio comprueba si Node.js está instalado en tu sistema. Si falta, el envoltorio descarga automáticamente una versión independiente. El complemento [nodejs] utiliza un método de descarga más fiable que el predeterminado.

Ten en cuenta que hay ventajas e inconvenientes. La primera ejecución tarda más tiempo mientras se descargan las dependencias. Los entornos CI con acceso restringido a la red podrían fallar. Y la versión PyPI a veces se retrasa unos días con respecto a los lanzamientos de npm.

Para la mayoría de los equipos de Python, el envoltorio funciona bien. Pero si tienes problemas, vuelve a la instalación npm. Es más fiable.

Ejecutar Pyright en un proyecto Python

Una vez instalado, ejecutar Pyright es muy sencillo. Ve al directorio de tu proyecto y ejecuta:

pyright

Eso es todo, en realidad. Pyright busca archivos Python, los analiza e informa de cualquier error de tipo que encuentre. No requiere una configuración compleja.

Lo que Pyright comprueba por defecto

¿Qué busca Pyright? Sin necesidad de configuración, realiza varias comprobaciones. Valida las anotaciones de tipo que coinciden con el uso real. Detecta variables indefinidas y código inaccesible. Verifica correctamente las importaciones. Señala incompatibilidades de tipos evidentes, como pasar una cadena cuando se espera un entero.

A continuación se muestra un ejemplo de resultado de un proyecto con errores:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informations

Cada error muestra la ruta del archivo, el número de línea, la columna y una descripción. El nombre de la regla entre paréntesis (como reportArgumentType) indica exactamente qué comprobación ha provocado el error. Esto es importante cuando deseas suprimir reglas específicas. Lo explicaremos en breve.

Comprender los códigos de salida

Pyright devuelve diferentes códigos de salida en función delresultado:

En los procesos de CI, normalmente se desea que la compilación falle con el código de salida 1. Los códigos de salida 2-4 indican que se ha producido un error en la herramienta, no en tu código.

Configuración de Pyright

Aunque Pyright funciona nada más instalarlo, los proyectos reales requieren personalización. Deberás especificar qué archivos se deben comprobar, qué versión de Python se debe utilizar y el nivel de rigor que debe tener el análisis. Veamos las opciones de configuración clave.

Modos de comprobación de tipos

Pyright ofrece cuatro niveles de rigor. El modo que elijasdetermina cuántas reglas se habilitan.

¿Qué modo debes elegir? Para proyectos nuevos, comienza conun estándar en modo. Detecta errores reales sin abrumarte con mensajes de error. ¿Trabajas con código heredado? El modo básico « » funciona mejor cuando se adopta la escritura gradualmente. Guarda el modoestricto de para bibliotecas e infraestructuras críticas en las que se requiere la máxima seguridad.

Advertencia: el salto de estándar a estricto es significativo. El modo estricto habilita unas 30 reglas adicionales, incluidos los requisitos de anotaciones de tipo en todos los parámetros de función y valores de retorno. Espera un aumento de 10 veces en los errores reportados al cambiar. Lo aprendí por las malas.

El modo estricto requiere anotaciones de tipo completas. Imagen del autor

Archivos de configuración

Pyright lee la configuración desde pyrightconfig.json o pyproject.toml. Si ambos existen, pyrightconfig.json tiene prioridad.

Aquí tienes un ejemplo mínimo pyrightconfig.json:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}

El equivalente en pyproject.toml:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"

El archivo de configuración controla el comportamiento de Pyright. Imagen del autor.

Aquí hay un detalle importante que llama la atención de muchas personas: si defines manualmente un exclude, esta reemplaza por completo los valores predeterminados. Incluye siempre node_modules, __pycache__ y tu entorno virtual en los patrones de exclusión personalizados. De lo contrario, Pyright intenta analizar tus dependencias, lo que provoca ralentizaciones importantes. Créeme, no querrás esperar 10 minutos para una comprobación de tipo.

Configuración del entorno virtual

¿Cómo encuentra Pyright los paquetes instalados? Tienes que indicarle dónde buscar. Configura esto con venvPath y venv:

{
  "venvPath": ".",
  "venv": ".venv"
}

Esto le indica a Pyright que busque paquetes en ./.venv. Si utilizas una ubicación de entorno virtual diferente, realiza los ajustes necesarios. Sin esto, Pyright no puede encontrar las dependencias instaladas y muestra errores de importación faltantes para todo.

Supresión de diagnósticos

A veces Pyright tiene razón desde el punto de vista técnico, pero de todos modos es necesario silenciar errores específicos. Quizás estés trabajando con código heredado o sepas más que el verificador de tipos en un caso específico. Puedes suprimir los errores en tres niveles.

Supresión del nivel de configuración

Desactivar reglas globalmente:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}

Supresión a nivel de archivo

Añade un comentario al principio del archivo:

# pyright: basic
# pyright: reportPrivateUsage=false

Supresión de nivel de línea

Suprimir una sola línea:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]

La sintaxis específica de la regla ([reportAssignmentType]) resulta útil cuando deseas silenciar una comprobación sin desactivar las demás de la misma línea.

Una vez cubierta la configuración, veamos cómo Pyright se integra en tu entorno de desarrollo.

Pyright en VS Code e IDE

Si eres como la mayoría de los programadores de Python, experimentarás Pyright a través de Pylance en lugar de la línea de comandos. Comprender esta relación te ayuda a configurar correctamente tu editor y evitar errores comunes.

Pyright contra Pylance

Pylance es la extensión VS Code de Microsoft que incluye el motor de comprobación de tipos de Pyright. Al instalar Pylance, obtienes Pyright automáticamente. Pero Pylance añade características que no están en el Pyright de código abierto:

• Resaltado semántico: variables coloreadas según su tipo
• Importación automática avanzada: sugerencias de importación más inteligentes
• Navegación por el código: Buscar todas las referencias en tu espacio de trabajo

Estas funciones son de código cerrado y solo están disponibles en VS Code. Si utilizas Neovim, Emacs u otro editor, obtienes la funcionalidad básica de Pyright, pero no estas funciones adicionales.

Pylance resalta los errores de tipo en el editor. Imagen del autor.

Configuración esencial de VS Code

Configura Pylance a través de los ajustes de VS Code:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}

La configuración « diagnosticMode » ( Analizar solo los archivos abiertos ) afecta al rendimiento. « "openFilesOnly" » (Analizar solo los archivos abiertos) analiza solo los archivos que tienes abiertos. « "workspace" » ( Analizar todo) analiza todo, pero utiliza más memoria y CPU.

Problemas comunes de configuración

La elección del intérprete es importante. Pylance utiliza el intérprete de Python seleccionado para buscar los paquetes instalados. Si de repente aparecen errores en paquetes que sabes que están instalados, comprueba que el intérprete correcto esté seleccionado en la barra de estado de VS Code.

La selección del intérprete afecta a las rutas de detección de paquetes. Imagen del autor.

Los valores predeterminados de CLI y Pylance son diferentes. Pylance establece por defecto typeCheckingMode como "off", mientras que la CLI lo establece por defecto como "standard". Pylance también añade automáticamente src a las rutas de búsqueda; la CLI no lo hace. Para garantizar un comportamiento coherente entre tu editor y CI, configura explícitamente todas las opciones en pyproject.toml.

El fenómeno del «código atenuado». Pylance oscurece el código inaccesible basándose en el análisis de tipos. Si el código aparece inactivo de forma inesperada, comprueba la función llamada inmediatamente antes. Una función tipificada como que devuelve un NoReturn hace que todo lo que viene después parezca inaccesible.

Pyright contra Mypy: Cuándo usar cada uno

Quizás te preguntes: ¿deberías usar Pyright o seguir con Mypy? Ambas herramientas están listas para su uso en producción, y tu elección dependerá de tu flujo de trabajo y tus requisitos. Permíteme explicarte las diferencias principales.

Velocidad y capacidad de respuesta

Pyright es aproximadamente entre 3 y 5 veces más rápido que Mypy en el análisis completo de proyectos y prácticamente instantáneo en las comprobaciones incrementales. Esto es especialmente importante durante el desarrollo, cuando se desea obtener una respuesta inmediata.

Mypy tiene un modo demonio (dmypy) que mejora el rendimiento, pero sigue siendo más lento y, en ocasiones, presenta problemas de almacenamiento en caché que requieren reiniciar el sistema.

Diferencias en la inferencia de tipos

Aquí es donde las cosas se ponen interesantes. Las herramientas infieren los tipos de manera diferente. Considera este código:

coordinates = (10, 20)

Pyright infiere un tuple[Literal[10], Literal[20]], conservando los valores exactos porque las tuplas son inmutables. Mypy deduce tuple[int, int], ampliándolo a tipos generales.

El enfoque de Pyright detecta más errores, pero en ocasiones provoca fricciones cuando las funciones esperan tipos generales. En la práctica, esto rara vez importa, ya que Literal[10] es un subtipo válido de int.

Análisis de código sin anotaciones

Esta es la mayor diferencia práctica, y supone un cambio revolucionario para los códigos heredados. Mypy omite las funciones sin anotar de forma predeterminada. Pyright los analiza de todos modos, detectando errores obvios incluso sin indicaciones de tipo.

Para bases de código heredadas con anotaciones escasas, Pyright actúa como un potente linter que detecta variables indefinidas y llamadas a métodos imposibles. Mypy trata esas funciones como «dinámicas» y las ignora.

Compatibilidad con complementos

Mypy admite complementos para marcos de trabajo como Django y SQLAlchemy. Estos complementos comprenden la magia de ORM y proporcionan tipos precisos para los atributos generados dinámicamente.

Pyright no tiene sistema de complementos. Depende completamente de los stubs de tipo. En 2026, la mayoría de las bibliotecas importantes cuentan con esbozos de alta calidad, por lo que esto importa menos que antes. Pero si utilizas un marco con metaprogramación pesada, comprueba si existen buenos stubs antes de comprometerteing con Pyright.

Utiliza Pylance (Pyright) durante el desarrollo para obtener comentarios instantáneos y considera la posibilidad de ejecutar tanto Pyright como Mypy en CI si tu proyecto utiliza complementos de marco.

Problemas comunes al usar Pyright

Cuando Pyright informa de errores inesperados, la causa suele ser uno de estos problemas.

Faltan stubs de tipo

¿Alguna vez has visto este error? Pyright se queja cuando no encuentra información sobre los tipos de un paquete:

Import "requests" could not be resolved (reportMissingImports)

Los stubs que faltan provocan errores de advertencia de importación. Imagen del autor.

En primer lugar, comprueba que el paquete está instalado en tu entorno virtual y que Pyright sabe dónde encontrarlo (utilizando la configuración de venvPath y venv que se ha explicado anteriormente).

Si el paquete está instalado pero carece de información sobre el tipo, instala los stubs de la comunidad:

pip install types-requests types-PyYAML types-redis

Para los paquetes sin stubs disponibles, tienes dos opciones. Puedes desactivar la advertencia con « "reportMissingTypeStubs": "none" » en tu configuración. O genera tú mismo borradores de stubs:

pyright --createstub some_package

Esto crea un archivo esqueleto .pyi que puedes rellenar con los métodos que realmente utilizas.

Errores en el gancho pre-commit

¿Pyright funciona localmente pero falla en los ganchos pre-commit? El problema suele ser el aislamiento del entorno. Pre-commit ejecuta hooks en entornos aislados que no pueden ver los paquetes instalados de tu proyecto.

Soluciona esto apuntando el gancho a tu entorno virtual:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]

Errores inesperados en modo estricto

¿Has activado el modo estricto y de repente ves miles de errores? No te asustes. Esto es normal. El modo estricto requiere anotaciones de tipo completas. Comienza con el modo básico o estándar, añade anotaciones de forma incremental y habilita el modo estricto solo en módulos completamente tipados.

Utiliza comentarios por archivo para mantener el código heredado en un modo indulgente:

# pyright: basic

Esto te permite aplicar controles estrictos al código nuevo mientras migras gradualmente el código antiguo.

Más allá de la resolución de problemas, aquí tienes algunas estrategias que harán que tu experiencia con Pyright sea más fluida desde el principio.

Mejores prácticas para el uso de Pyright

Después de trabajar con Pyright en diferentes proyectos, he aprendido algunas cosas que facilitan la adopción. La adopción de estas prácticas recomendadas de codificación garantiza que la comprobación de tipos siga siendo una ayuda y no un obstáculo.

Comienza con el modo estándar. Como se ha comentado anteriormente, detecta errores reales sin necesidad de anotaciones completas. Siempre puedes endurecer las normas más adelante.

Fija tu versión de Pyright. Pyright lanza actualizaciones con frecuencia y, en ocasiones, las nuevas versiones marcan código que antes se aceptaba. En CI, un pip install pyright sin fijar puede provocar fallos en la compilación del lunes por la mañana a partir de las versiones del fin de semana. He estado ahí. No es divertido.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"

# In requirements-dev.txt
pyright==1.1.408

Corregir los errores de forma gradual. No intentes eliminar 10 000 errores de una sola vez. Utiliza el arreglo strict para aplicar una comprobación estricta solo en directorios específicos:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}

Utiliza los archivos de configuración desde el principio. Incluso en proyectos pequeños, una configuración explícita evita sorpresas. Tómate cinco minutos para documentar tu versión de Python, la ruta del entorno virtual y el nivel de rigor elegido. Tu yo futuro te lo agradecerá.

No busques la perfección de inmediato. Al principio, utiliza # pyright: ignore con generosidad. Esto marca la deuda técnica de forma visible para que puedas ir eliminándola con el tiempo en lugar de bloquear el progreso. Lo perfecto es enemigo de lo bueno, especialmente cuando se adoptan nuevas herramientas.