0
# JSON Output
1
2
Structured diagnostic and analysis output for integration with development tools and CI/CD pipelines.
3
4
## Capabilities
5
6
### JSON Output Mode
7
8
Enable structured output format for machine consumption.
9
10
```bash { .api }
11
pyright --outputjson [options] files...
12
```
13
14
All output is directed to stdout as JSON, with console messages redirected to stderr.
15
16
### Main Results Structure
17
18
The primary output structure containing all analysis results.
19
20
```typescript { .api }
21
interface PyrightJsonResults {
22
version: string; // Pyright version
23
time: string; // Analysis timestamp
24
generalDiagnostics: PyrightJsonDiagnostic[]; // Diagnostic messages
25
summary: PyrightJsonSummary; // Analysis summary
26
typeCompleteness?: PyrightTypeCompletenessReport; // Optional completeness report
27
}
28
```
29
30
**Usage Example:**
31
32
```bash
33
pyright --outputjson src/ > analysis.json
34
```
35
36
### Diagnostic Structure
37
38
Individual diagnostic messages with location and severity information.
39
40
```typescript { .api }
41
interface PyrightJsonDiagnostic {
42
file: string; // File path where diagnostic occurred
43
severity: SeverityLevel; // Diagnostic severity level
44
message: string; // Human-readable diagnostic message
45
range?: Range; // Optional source location range
46
rule?: string; // Optional diagnostic rule identifier
47
}
48
49
type SeverityLevel = "error" | "warning" | "information";
50
```
51
52
### Summary Statistics
53
54
Aggregate information about the analysis results.
55
56
```typescript { .api }
57
interface PyrightJsonSummary {
58
filesAnalyzed: number; // Total number of files analyzed
59
errorCount: number; // Number of error diagnostics
60
warningCount: number; // Number of warning diagnostics
61
informationCount: number; // Number of information diagnostics
62
timeInSec: number; // Analysis duration in seconds
63
}
64
```
65
66
### Position and Range Types
67
68
Source code location information following LSP conventions.
69
70
```typescript { .api }
71
interface Range {
72
start: Position; // Start position of the range
73
end: Position; // End position of the range
74
}
75
76
interface Position {
77
line: number; // Line number (0-based)
78
character: number; // Character offset within line (0-based)
79
}
80
```
81
82
### Type Completeness Report
83
84
Detailed analysis of type annotation completeness for packages (available with `--verifytypes`).
85
86
```typescript { .api }
87
interface PyrightTypeCompletenessReport {
88
packageName: string; // Name of the analyzed package
89
packageRootDirectory?: string; // Package root directory path
90
moduleName: string; // Primary module name
91
moduleRootDirectory?: string; // Module root directory path
92
ignoreUnknownTypesFromImports: boolean; // Whether external unknowns are ignored
93
pyTypedPath?: string; // Path to py.typed file
94
exportedSymbolCounts: PyrightSymbolCount; // Statistics for exported symbols
95
otherSymbolCounts: PyrightSymbolCount; // Statistics for other symbols
96
missingFunctionDocStringCount: number; // Functions without docstrings
97
missingClassDocStringCount: number; // Classes without docstrings
98
missingDefaultParamCount: number; // Parameters without default values
99
completenessScore: number; // Overall completeness score (0.0-1.0)
100
modules: PyrightPublicModuleReport[]; // Module-level reports
101
symbols: PyrightPublicSymbolReport[]; // Symbol-level reports
102
}
103
```
104
105
**Usage Example:**
106
107
```bash
108
pyright --verifytypes mypackage --outputjson > completeness.json
109
```
110
111
### Symbol Count Statistics
112
113
Categorized counts of symbols by type knowledge status.
114
115
```typescript { .api }
116
interface PyrightSymbolCount {
117
withKnownType: number; // Symbols with fully known types
118
withAmbiguousType: number; // Symbols with partially known types
119
withUnknownType: number; // Symbols with unknown types
120
}
121
```
122
123
### Module Report
124
125
Information about analyzed modules.
126
127
```typescript { .api }
128
interface PyrightPublicModuleReport {
129
name: string; // Module name
130
}
131
```
132
133
### Symbol Report
134
135
Detailed information about individual symbols in the public API.
136
137
```typescript { .api }
138
interface PyrightPublicSymbolReport {
139
category: string; // Symbol category (function, class, variable, etc.)
140
name: string; // Fully qualified symbol name
141
referenceCount: number; // Number of references to this symbol
142
isTypeKnown: boolean; // Whether the symbol's type is fully known
143
isTypeAmbiguous: boolean; // Whether the symbol's type is ambiguous
144
isExported: boolean; // Whether the symbol is exported from its module
145
diagnostics: PyrightJsonDiagnostic[]; // Diagnostics associated with this symbol
146
alternateNames?: string[]; // Optional alternate names for the symbol
147
}
148
```
149
150
### Example JSON Output
151
152
**Basic Analysis Result:**
153
154
```json
155
{
156
"version": "1.1.405",
157
"time": "1699123456789",
158
"generalDiagnostics": [
159
{
160
"file": "/path/to/file.py",
161
"severity": "error",
162
"message": "Cannot assign to variable \"x\" of type \"int\" with value of type \"str\"",
163
"range": {
164
"start": { "line": 10, "character": 4 },
165
"end": { "line": 10, "character": 15 }
166
},
167
"rule": "reportGeneralTypeIssues"
168
}
169
],
170
"summary": {
171
"filesAnalyzed": 25,
172
"errorCount": 3,
173
"warningCount": 7,
174
"informationCount": 2,
175
"timeInSec": 1.234
176
}
177
}
178
```
179
180
**Type Completeness Report:**
181
182
```json
183
{
184
"version": "1.1.405",
185
"time": "1699123456789",
186
"generalDiagnostics": [],
187
"summary": {
188
"filesAnalyzed": 15,
189
"errorCount": 0,
190
"warningCount": 2,
191
"informationCount": 0,
192
"timeInSec": 0.856
193
},
194
"typeCompleteness": {
195
"packageName": "mypackage",
196
"moduleName": "mypackage",
197
"ignoreUnknownTypesFromImports": false,
198
"exportedSymbolCounts": {
199
"withKnownType": 45,
200
"withAmbiguousType": 3,
201
"withUnknownType": 2
202
},
203
"otherSymbolCounts": {
204
"withKnownType": 123,
205
"withAmbiguousType": 8,
206
"withUnknownType": 5
207
},
208
"missingFunctionDocStringCount": 12,
209
"missingClassDocStringCount": 3,
210
"missingDefaultParamCount": 8,
211
"completenessScore": 0.89,
212
"modules": [
213
{ "name": "mypackage" },
214
{ "name": "mypackage.utils" }
215
],
216
"symbols": [
217
{
218
"category": "function",
219
"name": "mypackage.main_function",
220
"referenceCount": 5,
221
"isTypeKnown": true,
222
"isTypeAmbiguous": false,
223
"isExported": true,
224
"diagnostics": []
225
}
226
]
227
}
228
}
229
```
230
231
### Processing JSON Output
232
233
**Python Example:**
234
235
```python
236
import json
237
import subprocess
238
239
# Run pyright and capture JSON output
240
result = subprocess.run(
241
["pyright", "--outputjson", "src/"],
242
capture_output=True,
243
text=True
244
)
245
246
# Parse JSON results
247
analysis = json.loads(result.stdout)
248
249
# Process diagnostics
250
for diagnostic in analysis["generalDiagnostics"]:
251
if diagnostic["severity"] == "error":
252
print(f"Error in {diagnostic['file']}: {diagnostic['message']}")
253
254
# Check summary
255
summary = analysis["summary"]
256
print(f"Analyzed {summary['filesAnalyzed']} files")
257
print(f"Found {summary['errorCount']} errors, {summary['warningCount']} warnings")
258
```
259
260
### Integration Patterns
261
262
**CI/CD Pipeline Integration:**
263
264
```bash
265
#!/bin/bash
266
# Type check and generate report
267
pyright --outputjson src/ > pyright-report.json
268
269
# Parse results and set exit code
270
if [ $(jq '.summary.errorCount' pyright-report.json) -gt 0 ]; then
271
echo "Type checking failed"
272
exit 1
273
fi
274
```
275
276
**Development Tooling:**
277
278
```javascript
279
const { exec } = require('child_process');
280
const fs = require('fs');
281
282
exec('pyright --outputjson src/', (error, stdout, stderr) => {
283
const results = JSON.parse(stdout);
284
285
// Extract diagnostics for IDE integration
286
const diagnostics = results.generalDiagnostics.map(d => ({
287
file: d.file,
288
line: d.range?.start.line || 0,
289
message: d.message,
290
severity: d.severity
291
}));
292
293
// Send to IDE or save to file
294
fs.writeFileSync('diagnostics.json', JSON.stringify(diagnostics, null, 2));
295
});
296
```
297
298
### Output Filtering
299
300
JSON output respects the `--level` option:
301
302
```bash
303
# Only errors in JSON output
304
pyright --outputjson --level error src/
305
306
# All diagnostics in JSON output
307
pyright --outputjson --level information src/
308
```
309
310
### API Stability
311
312
The JSON output interfaces are **publicly documented and stable**. These schemas are considered part of Pyright's public API contract.
313
314
### Compatibility
315
316
JSON output format is stable and versioned:
317
- `version` field indicates the Pyright version that generated the output
318
- Schema additions are backward-compatible
319
- New fields may be added but existing fields won't change meaning
320
- Consumers should handle unknown fields gracefully