0
# PyType
1
2
A static type checker and inferencer for Python that analyzes code without requiring explicit type annotations. PyType performs type inference on plain Python code to detect common programming errors like misspelled attributes and incorrect function calls, while also enforcing user-provided type annotations when present.
3
4
## Package Information
5
6
- **Package Name**: pytype
7
- **Language**: Python
8
- **Installation**: `pip install pytype`
9
- **Requirements**: Python 3.8-3.12
10
- **Platform Support**: Linux (primary), macOS 10.7+, Windows (via WSL)
11
12
## Core Imports
13
14
```python
15
import pytype
16
```
17
18
For direct API usage:
19
20
```python
21
from pytype import io
22
from pytype import config
23
from pytype import analyze
24
```
25
26
For working with PyTD (Python Type Declaration) system:
27
28
```python
29
from pytype.pytd import pytd
30
from pytype.pytd import pytd_utils
31
from pytype.pyi import parser
32
```
33
34
## Basic Usage
35
36
### Type Checking a Source String
37
38
```python
39
from pytype import io
40
41
# Check types in Python source code
42
source_code = '''
43
def add_numbers(x, y):
44
return x + y
45
46
result = add_numbers("hello", 42) # This will cause a type error
47
'''
48
49
try:
50
# Perform type checking
51
result = io.check_py(source_code)
52
print("Type checking completed successfully")
53
except Exception as e:
54
print(f"Type checking failed: {e}")
55
```
56
57
### Generating Type Stubs
58
59
```python
60
from pytype import io
61
62
# Generate .pyi type stub from source code
63
source_code = '''
64
class Calculator:
65
def add(self, x, y):
66
return x + y
67
68
def multiply(self, x, y):
69
return x * y
70
'''
71
72
# Generate PyTD AST
73
pyi_ast = io.generate_pyi_ast(source_code)
74
75
# Generate .pyi string
76
pyi_string = io.generate_pyi(source_code)
77
print(pyi_string)
78
```
79
80
### Processing Files with Configuration
81
82
```python
83
from pytype import config
84
from pytype import io
85
86
# Create configuration options
87
options = config.Options.create()
88
options.python_version = (3, 11)
89
options.output = "/path/to/output.pyi"
90
91
# Process a single file
92
result = io.process_one_file(options)
93
```
94
95
## Architecture
96
97
PyType's architecture consists of several key components:
98
99
- **Analysis Engine**: Core type inference and checking logic using abstract interpretation
100
- **PyTD System**: Python Type Declaration format for representing type information
101
- **PYI Parser**: Parser for Python type stub files (.pyi)
102
- **Configuration System**: Comprehensive options and settings management
103
- **CLI Tools**: Command-line interfaces for various analysis tasks
104
- **Import System**: Module resolution and loading infrastructure
105
106
This design enables PyType to analyze large Python codebases incrementally, generate precise type information, and integrate with existing Python development workflows through multiple interfaces.
107
108
## Capabilities
109
110
### Core Analysis Functions
111
112
High-level API for type checking and inference operations. These functions provide the primary programmatic interface to PyType's analysis capabilities.
113
114
```python { .api }
115
def check_py(src, options=None, loader=None): ...
116
def generate_pyi_ast(src, options=None, loader=None): ...
117
def generate_pyi(src, options=None, loader=None): ...
118
def process_one_file(options): ...
119
```
120
121
[Core Analysis](./core-analysis.md)
122
123
### Configuration Management
124
125
Comprehensive configuration system for controlling PyType's behavior, including Python version targeting, output formats, error handling, and analysis depth settings.
126
127
```python { .api }
128
class Options:
129
def __init__(argv_or_options, command_line=False): ...
130
@classmethod
131
def create(): ...
132
133
def make_parser(): ...
134
```
135
136
[Configuration](./configuration.md)
137
138
### PyTD Type System
139
140
Python Type Declaration system for representing, manipulating, and optimizing type information. Provides the foundation for PyType's type representation and stub file generation.
141
142
```python { .api }
143
class TypeDeclUnit: ...
144
class Class: ...
145
class Function: ...
146
def Print(ast, multiline_args=False): ...
147
def Optimize(ast, builtins, **kwargs): ...
148
```
149
150
[PyTD System](./pytd-system.md)
151
152
### PYI Parsing
153
154
Parser for Python type stub files (.pyi) that converts textual type declarations into PyTD AST representations for analysis and manipulation.
155
156
```python { .api }
157
def parse_string(src, filename=None, options=None): ...
158
def parse_pyi(src, filename, options): ...
159
def canonical_pyi(pyi, multiline_args=False, options=None): ...
160
```
161
162
[PYI Parsing](./pyi-parsing.md)
163
164
### Command-Line Tools
165
166
Complete set of command-line tools for different PyType workflows, from single-file analysis to project-wide type checking and stub generation.
167
168
```bash
169
pytype [files...] # Analyze Python projects
170
pytype-single file.py # Analyze single files
171
pytd [options] file.pytd # Process PyTD files
172
merge-pyi file.py file.pyi # Merge type stubs into source
173
annotate-ast file.py # Add type annotations to AST
174
pyxref [files...] # Generate cross-references
175
```
176
177
[CLI Tools](./cli-tools.md)
178
179
### Module Loading
180
181
Infrastructure for loading and resolving Python modules, PyTD files, and type information with support for custom import mappings and pickled type data.
182
183
```python { .api }
184
def create_loader(options, missing_modules=()): ...
185
class Loader: ...
186
class Module: ...
187
```
188
189
[Module Loading](./module-loading.md)
190
191
## Types
192
193
### Core Analysis Types
194
195
```python { .api }
196
class AnalysisResult:
197
"""Result of PyType analysis operations."""
198
def __init__(self, ast, errors, loader): ...
199
200
class Analysis:
201
"""Analysis context and results."""
202
def __init__(self, context, ast, ast_deps): ...
203
```
204
205
### Configuration Types
206
207
```python { .api }
208
class PostprocessingError(Exception):
209
"""Error during configuration postprocessing."""
210
```
211
212
### Utility Types
213
214
```python { .api }
215
class UsageError(Exception):
216
"""Top-level usage errors."""
217
```