Pyright for Python

Warnings

• gotcha The `pyright-python` wrapper handles Node.js installation via `nodeenv` by default. This can be less reliable than a direct Node.js installation, especially in restricted CI/CD environments or without `bash` availability. For more robust Node.js handling, install with the `nodejs` extra (`pip install pyright[nodejs]`).
  Fix: Use `pip install pyright[nodejs]` for installation. Ensure network access for Node.js download if not already present in PATH.
• gotcha When using `pyright-python` with `pre-commit`, it often runs in an isolated virtual environment, which can prevent Pyright from detecting your project's installed dependencies. This leads to 'unknown import' errors.
  Fix: Configure Pyright to explicitly use your project's virtual environment. Add a `[tool.pyright]` section to your `pyproject.toml` or create a `pyrightconfig.json` with `venvPath = "."` and `venv = ".venv"` (adjust `.venv` to your actual virtual environment directory name). Alternatively, configure pre-commit to install your dependencies into its hook environment.
• gotcha Manually defining an `exclude` option in `pyrightconfig.json` or `pyproject.toml` *replaces* Pyright's default excluded paths (like `node_modules`, `__pycache__`, virtual environments). Failing to re-include these common exclusions can cause massive slowdowns or hangs as Pyright attempts to analyze irrelevant files.
  Fix: Always explicitly include common exclusion paths (e.g., `node_modules`, `__pycache__`, your virtual environment directory) when providing a custom `exclude` list in your Pyright configuration.
• gotcha Pyright does not support a plugin system, unlike some other type checkers (e.g., MyPy). This means it may not fully understand or correctly type-check code that relies on MyPy-specific plugins (e.g., for complex ORMs like Django or some Pydantic features), potentially leading to false positives or missed errors.
  Fix: Consult Pyright's documentation for its native support for advanced type features. For libraries with known MyPy plugins, verify Pyright's compatibility or consider workarounds like `type: ignore` comments if needed. This may be a reason to use MyPy if deeply integrated with such libraries.

Install

• pip install pyright Standard installation
• pip install pyright[nodejs] Recommended: Includes Node.js binaries for reliability

Quickstart

This quickstart demonstrates how to run Pyright on a simple Python file. The `pyright` Python package primarily provides a command-line executable. Programmatic invocation within Python is typically done by calling the `pyright` command via `subprocess`.

import os

# Create a dummy Python file to check
with open("my_module.py", "w") as f:
    f.write("def greet(name: str) -> int:\n    return f'Hello, {name}'\n\nresult = greet('World')\n")

# Run pyright via the command line (typical usage)
# This is equivalent to `pyright my_module.py` in the terminal
import subprocess

try:
    # Using python -m pyright to ensure the installed package's executable is found
    process = subprocess.run(
        ['python', '-m', 'pyright', 'my_module.py'],
        capture_output=True,
        text=True,
        check=False  # Do not raise an exception for non-zero exit codes
    )
    print("Pyright Output:\n" + process.stdout)
    if process.stderr:
        print("Pyright Errors:\n" + process.stderr)
    if process.returncode != 0:
        print(f"Pyright exited with code {process.returncode}. Errors found.")
    else:
        print("Pyright completed with no errors.")
except FileNotFoundError:
    print("Error: 'pyright' command not found. Ensure pyright is installed and in PATH.")
except Exception as e:
    print(f"An error occurred: {e}")

# Clean up the dummy file
os.remove("my_module.py")