0
# Pyright
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pyright
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g pyright`
10
- **Minimum Node.js**: 14.0.0
11

12
## Core Imports
13

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

16
**Available interfaces:**
17
- Command-line binary: `pyright`
18
- Language server binary: `pyright-langserver`
19

20
## Basic Usage
21

22
### Command-Line Type Checking
23

24
```bash
25
# Check all Python files in current directory
26
pyright
27

28
# Check specific files
29
pyright src/main.py src/utils.py
30

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

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

37
# Watch for file changes
38
pyright --watch
39
```
40

41
### Global Installation
42

43
```bash
44
# Install globally
45
npm install -g pyright
46

47
# Verify installation
48
pyright --version
49

50
# Show help
51
pyright --help
52
```
53

54
## Architecture
55

56
Pyright is built around several key components:
57

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

65
## Capabilities
66

67
### Command-Line Interface
68

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

71
```bash { .api }
72
pyright [options] files...
73
```
74

75
**Key features:**
76
- Type checking with configurable diagnostic levels
77
- Type completeness verification for packages
78
- Type stub generation
79
- Multi-threaded analysis
80
- Watch mode for continuous checking
81
- JSON output for tooling integration
82

83
[CLI Tool](./cli-tool.md)
84

85
### Language Server Protocol
86

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

89
```bash { .api }
90
pyright-langserver
91
```
92

93
**Key features:**
94
- Real-time diagnostics and type checking
95
- Code completion with auto-import
96
- Go to definition and find references
97
- Symbol search and document outline
98
- Hover information and signature help
99
- Code actions and quick fixes
100

101
[Language Server](./language-server.md)
102

103
### JSON Output Format
104

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

107
```typescript { .api }
108
interface PyrightJsonResults {
109
  version: string;
110
  time: string;
111
  generalDiagnostics: PyrightJsonDiagnostic[];
112
  summary: PyrightJsonSummary;
113
  typeCompleteness?: PyrightTypeCompletenessReport;
114
}
115
```
116

117
**Key features:**
118
- Machine-readable diagnostic information
119
- Type completeness scoring and reporting
120
- Performance statistics
121
- Structured error and warning data
122

123
[JSON Output](./json-output.md)
124

125
## Exit Codes
126

127
```typescript { .api }
128
enum ExitStatus {
129
  NoErrors = 0,
130
  ErrorsReported = 1, 
131
  FatalError = 2,
132
  ConfigFileParseError = 3,
133
  ParameterError = 4,
134
}
135
```
136

137
## Configuration
138

139
### Configuration Files
140

141
Pyright supports configuration through:
142
- `pyrightconfig.json` - JSON configuration file
143
- `pyproject.toml` - TOML configuration in `[tool.pyright]` section
144

145
### Basic Configuration Example
146

147
```json
148
{
149
  "include": ["src"],
150
  "exclude": ["**/__pycache__"],
151
  "typeCheckingMode": "strict",
152
  "pythonVersion": "3.9",
153
  "reportMissingImports": true
154
}
155
```
156

157
## Integration Patterns
158

159
### CI/CD Integration
160

161
```bash
162
# Basic type checking with error exit code
163
pyright
164

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

168
# Check specific severity level
169
pyright --level error
170
```
171

172
### Editor Integration
173

174
Use `pyright-langserver` binary with LSP-compatible editors:
175
- Visual Studio Code (via Pylance extension)
176
- Vim/Neovim (via LSP plugins)
177
- Emacs (via lsp-mode)
178
- Any LSP-compatible editor
179

180
### Type Completeness Verification
181

182
```bash
183
# Verify type completeness of a package
184
pyright --verifytypes mypackage --outputjson
185
```
186

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