0
# CLI Tools
1

2
Complete set of command-line tools for different PyType workflows, from single-file analysis to project-wide type checking and stub generation. These tools provide the primary user interface to PyType's capabilities.
3

4
## Capabilities
5

6
### pytype - Project Analysis Tool
7

8
Main command-line interface for analyzing entire Python projects with comprehensive configuration options.
9

10
```bash
11
pytype [OPTIONS] [FILES...]
12
```
13

14
**Key Options:**
15
- `--python_version VERSION` - Target Python version (e.g., 3.11)
16
- `--output DIR` - Output directory for generated .pyi files
17
- `--check` - Check for type errors without generating stubs
18
- `--imports_map FILE` - Custom import mappings file
19
- `--exclude PATTERN` - Exclude files matching pattern
20
- `--jobs N` - Number of parallel processes
21

22
**Examples:**
23

24
```bash
25
# Analyze entire project
26
pytype src/
27

28
# Check types without generating stubs
29
pytype --check --python_version=3.11 src/
30

31
# Generate stubs with custom output directory
32
pytype --output=stubs/ --python_version=3.11 src/
33

34
# Parallel analysis with custom imports
35
pytype --jobs=4 --imports_map=.pytype/imports.txt src/
36
```
37

38
The pytype tool is implemented in:
39

40
```python { .api }
41
# pytype.tools.analyze_project.main
42
def main():
43
    """
44
    Main entry point for project-wide PyType analysis.
45
    
46
    Handles command-line argument parsing, project discovery,
47
    parallel analysis coordination, and result aggregation.
48
    
49
    Returns:
50
    int: Exit code (0 for success, non-zero for errors)
51
    """
52
```
53

54
### pytype-single - Single File Analysis
55

56
Analyzes individual Python files with detailed control over the analysis process.
57

58
```bash
59
pytype-single [OPTIONS] FILE
60
```
61

62
**Key Options:**
63
- `--output FILE` - Output .pyi file path
64
- `--check` - Type check only, no stub generation
65
- `--analyze-annotated` - Analyze functions with annotations
66
- `--quick` - Fast analysis mode
67
- `--maximum-depth N` - Analysis depth limit
68

69
**Examples:**
70

71
```bash
72
# Generate stub for single file
73
pytype-single --output=module.pyi module.py
74

75
# Quick type check
76
pytype-single --check --quick module.py
77

78
# Deep analysis with annotations
79
pytype-single --analyze-annotated --maximum-depth=5 module.py
80
```
81

82
The pytype-single tool is implemented in:
83

84
```python { .api }
85
# pytype.main
86
def main():
87
    """
88
    Main entry point for single-file PyType analysis.
89
    
90
    Processes command-line arguments and performs type analysis
91
    on a single Python file.
92
    
93
    Returns:
94
    int: Exit code (0 for success, non-zero for errors)
95
    """
96

97
def _run_pytype(options):
98
    """
99
    Core PyType execution logic.
100
    
101
    Parameters:
102
    - options (Options): Configuration for analysis
103
    
104
    Returns:
105
    Analysis results and error information
106
    """
107
```
108

109
### pytd - PyTD File Processor
110

111
Tool for working with PyTD (Python Type Declaration) files, including validation, optimization, and format conversion.
112

113
```bash
114
pytd [OPTIONS] FILE.pytd
115
```
116

117
**Key Options:**
118
- `--optimize` - Optimize PyTD AST
119
- `--verify` - Verify PyTD correctness
120
- `--print` - Pretty print PyTD content
121
- `--output FILE` - Output file for processed PyTD
122

123
**Examples:**
124

125
```bash
126
# Optimize PyTD file
127
pytd --optimize --output=optimized.pytd types.pytd
128

129
# Verify PyTD correctness
130
pytd --verify module.pytd
131

132
# Pretty print PyTD content
133
pytd --print types.pytd
134
```
135

136
The pytd tool is implemented in:
137

138
```python { .api }
139
# pytype.pytd.main
140
def main():
141
    """
142
    Main entry point for PyTD file processing.
143
    
144
    Handles PyTD file parsing, optimization, verification,
145
    and format conversion operations.
146
    
147
    Returns:
148
    int: Exit code (0 for success, non-zero for errors)
149
    """
150

151
def make_parser():
152
    """
153
    Create argument parser for pytd tool.
154
    
155
    Returns:
156
    argparse.ArgumentParser: Configured parser for pytd options
157
    """
158
```
159

160
### merge-pyi - Stub File Merger
161

162
Merges .pyi type stub information into Python source files, adding type annotations based on inferred types.
163

164
```bash
165
merge-pyi [OPTIONS] SOURCE.py STUB.pyi
166
```
167

168
**Key Options:**
169
- `--output FILE` - Output file with merged annotations
170
- `--in-place` - Modify source file in place
171
- `--no-backup` - Don't create backup files
172
- `--annotate-only FUNCTIONS` - Annotate only specified functions
173

174
**Examples:**
175

176
```bash
177
# Merge stub into source file
178
merge-pyi --output=annotated.py module.py module.pyi
179

180
# In-place annotation
181
merge-pyi --in-place module.py module.pyi
182

183
# Annotate specific functions only
184
merge-pyi --annotate-only="func1,func2" module.py module.pyi
185
```
186

187
The merge-pyi tool is implemented in:
188

189
```python { .api }
190
# pytype.tools.merge_pyi.main
191
def main(argv=None):
192
    """
193
    Main entry point for merging .pyi annotations into source files.
194
    
195
    Parameters:
196
    - argv (list, optional): Command line arguments
197
    
198
    Returns:
199
    int: Exit code (0 for success, non-zero for errors)
200
    """
201

202
def parse_args(argv):
203
    """
204
    Parse command line arguments for merge-pyi tool.
205
    
206
    Parameters:
207
    - argv (list): Command line arguments
208
    
209
    Returns:
210
    Parsed arguments object
211
    """
212
```
213

214
### annotate-ast - AST Annotator
215

216
Adds type annotations directly to Python AST nodes based on PyType's inference results.
217

218
```bash
219
annotate-ast [OPTIONS] FILE.py
220
```
221

222
**Key Options:**
223
- `--output FILE` - Output file with annotated AST
224
- `--python-version VERSION` - Target Python version
225
- `--preserve-existing` - Keep existing annotations
226

227
**Examples:**
228

229
```bash
230
# Annotate AST with inferred types
231
annotate-ast --output=annotated.py module.py
232

233
# Preserve existing annotations
234
annotate-ast --preserve-existing module.py
235
```
236

237
The annotate-ast tool is implemented in:
238

239
```python { .api }
240
# pytype.tools.annotate_ast.main
241
def main():
242
    """
243
    Main entry point for AST annotation.
244
    
245
    Analyzes Python source and adds type annotations
246
    directly to AST nodes based on inference results.
247
    
248
    Returns:
249
    int: Exit code (0 for success, non-zero for errors)
250
    """
251

252
def annotate_source(src, ast_factory, options):
253
    """
254
    Annotate source code with type information.
255
    
256
    Parameters:
257
    - src (str): Python source code
258
    - ast_factory: AST creation factory
259
    - options (Options): Analysis configuration
260
    
261
    Returns:
262
    Annotated AST with type information
263
    """
264
```
265

266
### pyxref - Cross-Reference Generator
267

268
Generates cross-reference information from Python projects, creating indexes of symbol definitions and usage.
269

270
```bash
271
pyxref [OPTIONS] [FILES...]
272
```
273

274
**Key Options:**
275
- `--output DIR` - Output directory for cross-reference data
276
- `--format FORMAT` - Output format (json, html, text)
277
- `--include-builtin` - Include built-in symbol references
278

279
**Examples:**
280

281
```bash
282
# Generate cross-reference data
283
pyxref --output=xref/ --format=json src/
284

285
# HTML cross-reference with builtins
286
pyxref --output=docs/ --format=html --include-builtin src/
287
```
288

289
The pyxref tool is implemented in:
290

291
```python { .api }
292
# pytype.tools.xref.main
293
def main():
294
    """
295
    Main entry point for cross-reference generation.
296
    
297
    Analyzes Python projects and generates comprehensive
298
    cross-reference information for symbols and their usage.
299
    
300
    Returns:
301
    int: Exit code (0 for success, non-zero for errors)
302
    """
303
```
304

305
## Common Usage Patterns
306

307
### CI/CD Integration
308

309
```bash
310
#!/bin/bash
311
# CI script for type checking
312

313
# Quick type check for pull requests
314
if [ "$CI_PULL_REQUEST" = "true" ]; then
315
    pytype --check --quick --jobs=2 src/
316
else
317
    # Full analysis for main branch
318
    pytype --output=stubs/ --python-version=3.11 src/
319
fi
320
```
321

322
### Development Workflow
323

324
```bash
325
# 1. Initial project setup
326
pytype --output=.pytype/pyi/ src/
327

328
# 2. Check specific file during development
329
pytype-single --check --quick src/mymodule.py
330

331
# 3. Generate updated stubs after changes
332
pytype-single --output=.pytype/pyi/mymodule.pyi src/mymodule.py
333

334
# 4. Merge annotations for release
335
merge-pyi --output=src/mymodule_annotated.py src/mymodule.py .pytype/pyi/mymodule.pyi
336
```
337

338
### Large Project Analysis
339

340
```bash
341
# Parallel analysis with custom configuration
342
pytype \
343
  --jobs=8 \
344
  --python-version=3.11 \
345
  --output=stubs/ \
346
  --imports-map=.pytype/imports.txt \
347
  --exclude="**/test_*.py" \
348
  --exclude="**/conftest.py" \
349
  src/
350
```
351

352
### Stub Generation Pipeline
353

354
```bash
355
#!/bin/bash
356
# Generate and optimize stubs
357

358
# 1. Generate initial stubs
359
pytype --output=raw_stubs/ src/
360

361
# 2. Optimize PyTD files
362
for file in raw_stubs/*.pyi; do
363
    pytd --optimize --output="optimized_stubs/$(basename "$file")" "$file"
364
done
365

366
# 3. Verify optimized stubs
367
for file in optimized_stubs/*.pyi; do
368
    pytd --verify "$file" || echo "Verification failed for $file"
369
done
370
```
371

372
## Exit Codes
373

374
All PyType CLI tools use consistent exit codes:
375

376
- `0` - Success, no errors found
377
- `1` - Type errors found (when using --check)
378
- `2` - Command-line argument errors
379
- `3` - File not found or permission errors
380
- `4` - Internal PyType errors
381
- `5` - Python version compatibility errors
382

383
## Configuration Files
384

385
CLI tools support configuration through:
386

387
- `.pytype/` directory for project settings
388
- `pyproject.toml` for PEP 518 configuration
389
- Command-line arguments (highest priority)
390

391
Example `.pytype/imports.txt`:
392
```
393
# Custom import mappings
394
mypackage.internal mypackage._internal
395
external_lib /path/to/external/stubs
396
```
397

398
## Integration with Other Tools
399

400
```bash
401
# Integration with mypy
402
pytype --output=stubs/ src/ && mypy --check-untyped-defs src/
403

404
# Integration with black formatter
405
pytype-single module.py && black module.py
406

407
# Integration with pytest
408
pytype --check src/ && pytest tests/
409
```