0
# Configuration Management
1

2
Comprehensive configuration system for controlling PyType's behavior, including Python version targeting, output formats, error handling, and analysis depth settings. The configuration system supports both programmatic and command-line usage patterns.
3

4
## Capabilities
5

6
### Options Class
7

8
Main configuration class that manages all PyType settings, supporting both direct instantiation and command-line argument parsing.
9

10
```python { .api }
11
class Options:
12
    """
13
    Main configuration class for PyType analysis settings.
14
    
15
    Supports initialization from command line arguments or direct parameter setting.
16
    Contains all options for controlling PyType's analysis behavior.
17
    """
18
    
19
    def __init__(self, argv_or_options, command_line=False):
20
        """
21
        Initialize Options from arguments or existing options.
22
        
23
        Parameters:
24
        - argv_or_options: Command line arguments list or existing Options object
25
        - command_line (bool): Whether arguments come from command line
26
        
27
        Raises:
28
        PostprocessingError: If configuration validation fails
29
        """
30
    
31
    @classmethod
32
    def create(cls, input_filename=None, **kwargs):
33
        """
34
        Create Options instance with default settings.
35
        
36
        Parameters:
37
        - input_filename (str, optional): Input file for configuration
38
        - **kwargs: Additional configuration options
39
        
40
        Returns:
41
        Options: New Options object with configured settings
42
        """
43
```
44

45
Example usage:
46

47
```python
48
from pytype import config
49

50
# Create with defaults
51
options = config.Options.create()
52

53
# Set common options
54
options.python_version = (3, 11)
55
options.output = "output.pyi"
56
options.check = True
57
options.analyze_annotated = True
58

59
# Create from command line args
60
import sys
61
options = config.Options(sys.argv[1:], command_line=True)
62
```
63

64
### Argument Parser
65

66
Creates command-line argument parser with all PyType options, enabling consistent CLI behavior across all PyType tools.
67

68
```python { .api }
69
def make_parser():
70
    """
71
    Create argument parser for PyType command line options.
72
    
73
    Returns:
74
    argparse.ArgumentParser: Configured parser with all PyType options
75
    """
76
```
77

78
Example usage:
79

80
```python
81
from pytype import config
82

83
# Create parser and parse arguments
84
parser = config.make_parser()
85
args = parser.parse_args(['--python-version=3.11', '--check', 'file.py'])
86

87
# Create options from parsed arguments
88
options = config.Options(args, command_line=True)
89
```
90

91
### Key Configuration Options
92

93
The Options class contains numerous configuration attributes organized into functional groups:
94

95
#### Python Version and Environment
96

97
```python
98
# Python version targeting
99
options.python_version = (3, 11)      # Target Python version tuple
100
options.python_exe = "/usr/bin/python3"  # Python executable path
101

102
# Import system
103
options.pythonpath = ["/path/to/modules"]  # Module search paths
104
options.imports_map = "imports.txt"        # Custom import mappings
105
options.module = "mymodule"                # Module name for analysis
106
```
107

108
#### Analysis Control
109

110
```python
111
# Analysis behavior
112
options.check = True                    # Enable type checking
113
options.analyze_annotated = True        # Analyze annotated functions
114
options.quick = False                   # Quick analysis mode
115
options.strict_import = False           # Strict import checking
116

117
# Depth control
118
options.main_only = False               # Analyze only main module
119
options.maximum_depth = 3               # Maximum analysis depth
120
```
121

122
#### Output Control
123

124
```python
125
# Output settings
126
options.output = "output.pyi"           # Output file path
127
options.output_cfg = "cfg.txt"          # Control flow graph output
128
options.output_typegraph = "graph.svg"  # Type graph visualization
129

130
# Error handling
131
options.no_report_errors = False        # Suppress error reporting
132
options.return_success = False          # Always return success
133
```
134

135
#### Feature Flags
136

137
```python
138
# Optional features
139
options.protocols = True                # Enable protocol checking  
140
options.strict_namedtuple_checks = True # Strict namedtuple validation
141
options.strict_parameter_checks = False # Strict parameter checking
142
options.overriding_parameter_count_checks = True  # Parameter count validation
143
```
144

145
## Configuration Constants
146

147
```python { .api }
148
# Logging levels
149
LOG_LEVELS: list  # Available logging levels ['INFO', 'WARNING', 'ERROR']
150

151
# Option groups for organization
152
BASIC_OPTIONS: list      # Essential command-line options
153
FEATURE_FLAGS: list      # Optional feature toggles  
154
OUTPUT_OPTIONS: list     # Output control options
155
IMPORT_OPTIONS: list     # Import system options
156

157
# Default values
158
DEFAULT_PYTHON_VERSION: tuple  # Default Python version
159
DEFAULT_PROTOCOLS: bool        # Default protocol checking setting
160
```
161

162
Example of comprehensive configuration:
163

164
```python
165
from pytype import config
166

167
# Create and configure options
168
options = config.Options.create()
169

170
# Set target environment
171
options.python_version = (3, 11)
172
options.pythonpath = ["/my/project/src", "/my/project/lib"]
173

174
# Configure analysis behavior
175
options.check = True
176
options.analyze_annotated = True
177
options.strict_import = True
178
options.protocols = True
179

180
# Set output preferences  
181
options.output = "/output/stubs/"
182
options.no_report_errors = False
183

184
# Enable advanced features
185
options.strict_namedtuple_checks = True
186
options.overriding_parameter_count_checks = True
187

188
# Use in analysis
189
from pytype import io
190
result = io.check_py(source_code, options=options)
191
```
192

193
## Error Handling
194

195
```python { .api }
196
class PostprocessingError(Exception):
197
    """
198
    Error raised during configuration postprocessing.
199
    
200
    Occurs when configuration validation fails or incompatible
201
    options are specified together.
202
    """
203

204
class UsageError(Exception):
205
    """
206
    Error raised for invalid command-line usage.
207
    
208
    Occurs when invalid arguments or option combinations are provided.
209
    """
210
```
211

212
## Advanced Configuration Patterns
213

214
### Project-Wide Settings
215

216
```python
217
from pytype import config
218
import os
219

220
# Load project configuration
221
options = config.Options.create()
222
options.python_version = (3, 11)
223
options.pythonpath = [
224
    os.path.join(project_root, "src"),
225
    os.path.join(project_root, "lib"),
226
]
227

228
# Set up imports map for complex projects
229
options.imports_map = os.path.join(project_root, ".pytype", "imports.txt")
230

231
# Configure output structure
232
options.output = os.path.join(project_root, "stubs")
233
```
234

235
### Performance Tuning
236

237
```python
238
# Quick analysis for CI/CD
239
options = config.Options.create()
240
options.quick = True
241
options.maximum_depth = 1
242
options.main_only = True
243

244
# Thorough analysis for release
245
options = config.Options.create()  
246
options.maximum_depth = 5
247
options.analyze_annotated = True
248
options.protocols = True
249
options.strict_import = True
250
```