Pyright

Pyright is a full-featured, standards-based static type checker for Python designed for high performance and compatibility with large Python source bases. It provides both a command-line tool and Visual Studio Code extension, offering comprehensive Python type checking capabilities including support for type annotations, generics, protocol checking, and advanced type inference.

Package Information

• Package Name: pyright
• Package Type: npm
• Language: TypeScript
• Installation: npm install -g pyright
• Minimum Node.js: 14.0.0

Core Imports

Pyright is designed as a CLI tool and language server, not as a Node.js library. It does not export modules for programmatic use.

Available interfaces:

• Command-line binary: pyright
• Language server binary: pyright-langserver

Basic Usage

Command-Line Type Checking

# Check all Python files in current directory
pyright

# Check specific files
pyright src/main.py src/utils.py

# Check files with configuration
pyright --project ./pyrightconfig.json

# Get JSON output for tooling integration
pyright --outputjson src/

# Watch for file changes
pyright --watch

Global Installation

# Install globally
npm install -g pyright

# Verify installation
pyright --version

# Show help
pyright --help

Architecture

Pyright is built around several key components:

• CLI Type Checker: Primary interface for static analysis of Python code
• Language Server: LSP-compliant server for editor integration with real-time type checking
• Configuration System: Support for pyrightconfig.json and pyproject.toml configuration files
• Multi-threading Engine: Parallel analysis capabilities for large codebases
• JSON Output: Structured diagnostic and type completeness reporting
• File Watching: Incremental analysis with file system monitoring

Capabilities

Command-Line Interface

Complete command-line type checking tool with extensive configuration options, multi-threading support, and structured output formats.

pyright [options] files...

Key features:

• Type checking with configurable diagnostic levels
• Type completeness verification for packages
• Type stub generation
• Multi-threaded analysis
• Watch mode for continuous checking
• JSON output for tooling integration

CLI Tool

Language Server Protocol

LSP-compliant language server providing real-time type checking and IntelliSense features for Python development environments.

pyright-langserver

Key features:

• Real-time diagnostics and type checking
• Code completion with auto-import
• Go to definition and find references
• Symbol search and document outline
• Hover information and signature help
• Code actions and quick fixes

Language Server

JSON Output Format

Structured diagnostic and analysis output for integration with development tools and CI/CD pipelines.

interface PyrightJsonResults {
  version: string;
  time: string;
  generalDiagnostics: PyrightJsonDiagnostic[];
  summary: PyrightJsonSummary;
  typeCompleteness?: PyrightTypeCompletenessReport;
}

Key features:

• Machine-readable diagnostic information
• Type completeness scoring and reporting
• Performance statistics
• Structured error and warning data

JSON Output

Exit Codes

enum ExitStatus {
  NoErrors = 0,
  ErrorsReported = 1, 
  FatalError = 2,
  ConfigFileParseError = 3,
  ParameterError = 4,
}

Configuration

Configuration Files

Pyright supports configuration through:

• pyrightconfig.json - JSON configuration file
• pyproject.toml - TOML configuration in [tool.pyright] section

Basic Configuration Example

{
  "include": ["src"],
  "exclude": ["**/__pycache__"],
  "typeCheckingMode": "strict",
  "pythonVersion": "3.9",
  "reportMissingImports": true
}

Integration Patterns

CI/CD Integration

# Basic type checking with error exit code
pyright

# JSON output for parsing results
pyright --outputjson > pyright-results.json

# Check specific severity level
pyright --level error

Editor Integration

Use pyright-langserver binary with LSP-compatible editors:

• Visual Studio Code (via Pylance extension)
• Vim/Neovim (via LSP plugins)
• Emacs (via lsp-mode)
• Any LSP-compatible editor

Type Completeness Verification

# Verify type completeness of a package
pyright --verifytypes mypackage --outputjson

This generates detailed type completeness reports for library maintainers and consumers.