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.