0
# Configuration
1

2
Global configuration settings and debugging utilities for controlling jedi behavior, performance tuning, and troubleshooting analysis issues. Provides comprehensive control over completion behavior, caching, dynamic analysis, and debugging output.
3

4
## Capabilities
5

6
### Debug Configuration
7

8
Configure debug output and logging for troubleshooting jedi analysis issues.
9

10
```python { .api }
11
def set_debug_function(func_cb=debug.print_to_stdout, warnings=True, 
12
                       notices=True, speed=True):
13
    """
14
    Configure debug output function and levels.
15
    
16
    Parameters:
17
    - func_cb (callable): Debug callback function. Default prints to stdout.
18
    - warnings (bool): Enable warning messages. Default True.
19
    - notices (bool): Enable notice messages. Default True.
20
    - speed (bool): Enable speed/performance messages. Default True.
21
    """
22
```
23

24
**Usage Example:**
25
```python
26
import jedi
27

28
# Basic debug setup (print to stdout)
29
jedi.set_debug_function()
30

31
# Custom debug function
32
def custom_debug(level, message):
33
    print(f"[JEDI-{level}] {message}")
34

35
jedi.set_debug_function(custom_debug, warnings=True, notices=False, speed=True)
36

37
# File-based logging
38
import logging
39
logging.basicConfig(filename='jedi_debug.log', level=logging.DEBUG)
40

41
def log_debug(level, message):
42
    logging.debug(f"{level}: {message}")
43

44
jedi.set_debug_function(log_debug)
45

46
# Analyze code with debug output
47
code = '''
48
import json
49
json.loads("test").'''
50

51
script = jedi.Script(code=code)
52
completions = script.complete(line=2, column=20)  # Debug info will be output
53
```
54

55
### Module Preloading
56

57
Preload modules for improved performance in repeated analysis operations.
58

59
```python { .api }
60
def preload_module(*modules):
61
    """
62
    Preload modules for better performance.
63
    
64
    Parameters:
65
    - modules: Module names to preload.
66
    """
67
```
68

69
**Usage Example:**
70
```python
71
import jedi
72

73
# Preload commonly used modules
74
jedi.preload_module('json', 'os', 'sys', 'collections', 'itertools')
75

76
# Preload third-party modules
77
jedi.preload_module('numpy', 'pandas', 'requests', 'django')
78

79
# Preload project-specific modules
80
jedi.preload_module('my_project.utils', 'my_project.models')
81

82
# Now analysis will be faster for these modules
83
code = '''
84
import json
85
import numpy as np
86
from my_project.utils import helper_function
87

88
json.'''
89

90
script = jedi.Script(code=code)
91
completions = script.complete(line=4, column=5)  # Faster due to preloading
92
```
93

94
### Completion Behavior Settings
95

96
Control completion output behavior and formatting.
97

98
```python { .api }
99
# jedi.settings module
100
case_insensitive_completion: bool = True  # Case insensitive completions
101
add_bracket_after_function: bool = False  # Add brackets after function completions
102
```
103

104
**Usage Example:**
105
```python
106
import jedi
107

108
# Configure case sensitivity
109
jedi.settings.case_insensitive_completion = False  # Exact case matching
110

111
code = '''
112
class MyClass:
113
    def MyMethod(self):
114
        pass
115

116
obj = MyClass()
117
obj.my'''  # Won't match MyMethod with case_insensitive_completion=False
118

119
script = jedi.Script(code=code)
120
completions = script.complete(line=6, column=6)
121
print(f"Completions: {[c.name for c in completions]}")
122

123
# Enable automatic bracket addition
124
jedi.settings.add_bracket_after_function = True
125

126
function_code = '''
127
def my_function():
128
    pass
129

130
my_func'''
131

132
script = jedi.Script(code=function_code)
133
completions = script.complete(line=4, column=7)
134
for comp in completions:
135
    if comp.name == 'my_function':
136
        print(f"Completion: {comp.name}, Complete: {comp.complete}")
137
        # Will show '(' when add_bracket_after_function=True
138
```
139

140
### Cache Configuration
141

142
Configure filesystem caching and performance settings.
143

144
```python { .api }
145
# jedi.settings module
146
cache_directory: str  # Cache storage directory path
147
call_signatures_validity: float = 3.0  # Function call cache duration in seconds
148
_cropped_file_size: int = 10000000  # Max file size for analysis (10MB)
149
```
150

151
**Usage Example:**
152
```python
153
import jedi
154
import os
155

156
# Check current cache directory
157
print(f"Current cache directory: {jedi.settings.cache_directory}")
158

159
# Set custom cache directory
160
custom_cache = "/tmp/my_jedi_cache"
161
os.makedirs(custom_cache, exist_ok=True)
162
jedi.settings.cache_directory = custom_cache
163

164
# Configure call signature caching
165
jedi.settings.call_signatures_validity = 10.0  # Cache for 10 seconds
166

167
# Test signature caching
168
code = '''
169
def my_function(param1, param2, param3):
170
    return param1 + param2 + param3
171

172
my_function('''
173

174
script = jedi.Script(code=code)
175

176
# First call - will be cached
177
signatures1 = script.get_signatures(line=4, column=12)
178
print("First signature call")
179

180
# Second call within cache validity - will use cache
181
signatures2 = script.get_signatures(line=4, column=12)
182
print("Second signature call (cached)")
183
```
184

185
### Parser Configuration
186

187
Control parser behavior and performance optimization.
188

189
```python { .api }
190
# jedi.settings module
191
fast_parser: bool = True  # Use Parso's diff parser for performance
192
```
193

194
**Usage Example:**
195
```python
196
import jedi
197

198
# Disable fast parser for debugging or thread safety
199
jedi.settings.fast_parser = False
200

201
# Warning: This makes jedi thread-safe but slower
202
# Useful when using multiple Script instances simultaneously
203

204
import threading
205

206
def analyze_code(code, results, index):
207
    script = jedi.Script(code=code)
208
    completions = script.complete()
209
    results[index] = len(completions)
210

211
# Multiple threads can safely use jedi with fast_parser=False
212
results = {}
213
threads = []
214

215
codes = [
216
    "import json; json.",
217
    "import os; os.",
218
    "import sys; sys."
219
]
220

221
for i, code in enumerate(codes):
222
    thread = threading.Thread(target=analyze_code, args=(code, results, i))
223
    threads.append(thread)
224
    thread.start()
225

226
for thread in threads:
227
    thread.join()
228

229
print(f"Thread results: {results}")
230

231
# Re-enable for better performance in single-threaded usage
232
jedi.settings.fast_parser = True
233
```
234

235
### Dynamic Analysis Configuration
236

237
Control dynamic analysis features and behavior.
238

239
```python { .api }
240
# jedi.settings module
241
dynamic_array_additions: bool = True      # Analyze array.append() etc.
242
dynamic_params: bool = True               # Dynamic parameter completion
243
dynamic_params_for_other_modules: bool = True  # Dynamic params for other modules
244
dynamic_flow_information: bool = True     # Use isinstance() for type inference
245
auto_import_modules: list = ['gi']        # Modules to import rather than analyze
246
allow_unsafe_interpreter_executions: bool = True  # Allow descriptor evaluation
247
```
248

249
**Usage Example:**
250
```python
251
import jedi
252

253
# Configure dynamic analysis
254
jedi.settings.dynamic_array_additions = True
255
jedi.settings.dynamic_params = True
256
jedi.settings.dynamic_flow_information = True
257

258
# Test dynamic array analysis
259
array_code = '''
260
my_list = []
261
my_list.append("item1")
262
my_list.append("item2")
263
my_list.'''  # Should know it contains strings
264

265
script = jedi.Script(code=array_code)
266
completions = script.complete(line=4, column=8)
267
print("Array completions:")
268
for comp in completions[:5]:
269
    print(f"  {comp.name}: {comp.description}")
270

271
# Test isinstance flow analysis
272
isinstance_code = '''
273
def process_value(value):
274
    if isinstance(value, str):
275
        return value.  # Should show string methods
276
    elif isinstance(value, list):
277
        return value.  # Should show list methods
278
    return value
279
'''
280

281
script = jedi.Script(code=isinstance_code)
282

283
# String context completions
284
str_completions = script.complete(line=3, column=21)
285
print("\nString context completions:")
286
for comp in str_completions[:3]:
287
    print(f"  {comp.name}")
288

289
# List context completions
290
list_completions = script.complete(line=5, column=21)
291
print("\nList context completions:")
292
for comp in list_completions[:3]:
293
    print(f"  {comp.name}")
294

295
# Configure auto-import modules (modules that should be imported, not analyzed)
296
jedi.settings.auto_import_modules = ['gi', 'tensorflow', 'torch']
297

298
# Disable unsafe executions for security
299
jedi.settings.allow_unsafe_interpreter_executions = False
300
```
301

302
### Performance Tuning
303

304
Optimize jedi performance for different use cases.
305

306
**Usage Example:**
307
```python
308
import jedi
309

310
# High-performance configuration for IDE usage
311
def configure_for_ide():
312
    jedi.settings.fast_parser = True
313
    jedi.settings.call_signatures_validity = 5.0
314
    jedi.settings.dynamic_params = True
315
    jedi.settings.dynamic_array_additions = True
316
    
317
    # Preload common modules
318
    jedi.preload_module(
319
        'os', 'sys', 'json', 'collections', 'itertools',
320
        'functools', 'operator', 'typing'
321
    )
322

323
# Conservative configuration for reliability
324
def configure_for_reliability():
325
    jedi.settings.fast_parser = False  # Thread-safe
326
    jedi.settings.dynamic_params = False  # More predictable
327
    jedi.settings.allow_unsafe_interpreter_executions = False  # Safer
328

329
# Minimal configuration for basic completions
330
def configure_minimal():
331
    jedi.settings.dynamic_array_additions = False
332
    jedi.settings.dynamic_params = False
333
    jedi.settings.dynamic_params_for_other_modules = False
334
    jedi.settings.dynamic_flow_information = False
335

336
# Apply configuration based on use case
337
configure_for_ide()
338

339
# Test performance
340
import time
341

342
code = '''
343
import collections
344
from typing import List, Dict
345

346
def process_data(items: List[str]) -> Dict[str, int]:
347
    counter = collections.Counter(items)
348
    return dict(counter)
349

350
counter.'''
351

352
script = jedi.Script(code=code)
353

354
start_time = time.time()
355
completions = script.complete(line=8, column=8)
356
end_time = time.time()
357

358
print(f"Completion time: {end_time - start_time:.4f} seconds")
359
print(f"Number of completions: {len(completions)}")
360
```
361

362
### Environment-Specific Configuration
363

364
Configure jedi for different environments and contexts.
365

366
**Usage Example:**
367
```python
368
import jedi
369
import platform
370

371
# Configure based on operating system
372
if platform.system() == "Windows":
373
    # Windows-specific cache directory
374
    import os
375
    jedi.settings.cache_directory = os.path.join(
376
        os.getenv('LOCALAPPDATA', os.path.expanduser('~')),
377
        'Jedi', 'Cache'
378
    )
379
elif platform.system() == "Darwin":
380
    # macOS cache directory
381
    jedi.settings.cache_directory = os.path.expanduser('~/Library/Caches/Jedi')
382
else:
383
    # Linux cache directory
384
    import os
385
    cache_home = os.getenv('XDG_CACHE_HOME', os.path.expanduser('~/.cache'))
386
    jedi.settings.cache_directory = os.path.join(cache_home, 'jedi')
387

388
# Configure for different Python versions
389
import sys
390

391
if sys.version_info >= (3, 9):
392
    # Enable advanced features for newer Python
393
    jedi.settings.dynamic_flow_information = True
394
    jedi.settings.dynamic_params_for_other_modules = True
395
else:
396
    # Conservative settings for older Python
397
    jedi.settings.dynamic_flow_information = False
398
    jedi.settings.dynamic_params_for_other_modules = False
399

400
# Configure for different usage patterns
401
def configure_for_repl():
402
    """Configuration optimized for REPL usage."""
403
    jedi.settings.call_signatures_validity = 1.0  # Shorter cache
404
    jedi.settings.allow_unsafe_interpreter_executions = True
405
    jedi.settings.dynamic_array_additions = True
406

407
def configure_for_static_analysis():
408
    """Configuration optimized for static analysis."""
409
    jedi.settings.allow_unsafe_interpreter_executions = False
410
    jedi.settings.fast_parser = False  # More thorough analysis
411
    jedi.settings.dynamic_params = False  # Deterministic results
412

413
# Apply REPL configuration
414
configure_for_repl()
415
```
416

417
## Configuration Settings Reference
418

419
### Completion Settings
420
- `case_insensitive_completion`: Boolean, default `True`
421
- `add_bracket_after_function`: Boolean, default `False`
422

423
### Cache Settings  
424
- `cache_directory`: String, platform-specific default
425
- `call_signatures_validity`: Float, default `3.0` seconds
426

427
### Parser Settings
428
- `fast_parser`: Boolean, default `True`
429

430
### Dynamic Analysis Settings
431
- `dynamic_array_additions`: Boolean, default `True`  
432
- `dynamic_params`: Boolean, default `True`
433
- `dynamic_params_for_other_modules`: Boolean, default `True`
434
- `dynamic_flow_information`: Boolean, default `True`
435
- `auto_import_modules`: List, default `['gi']`
436

437
### Interpreter Settings
438
- `allow_unsafe_interpreter_executions`: Boolean, default `True`