0
# Configuration System
1

2
JupyterLab settings integration with support for formatter-specific options, format-on-save settings, error handling preferences, and language-specific default formatters.
3

4
## Capabilities
5

6
### Settings Schema
7

8
The extension provides a comprehensive JSON schema for configuration.
9

10
**Schema Location**: `schema/settings.json`
11

12
### Core Configuration Options
13

14
#### Format-on-Save Settings
15

16
```json { .api }
17
{
18
  "formatOnSave": {
19
    "type": "boolean",
20
    "default": false,
21
    "description": "Automatically format code when saving files"
22
  }
23
}
24
```
25

26
#### Caching Settings
27

28
```json { .api }
29
{
30
  "cacheFormatters": {
31
    "type": "boolean", 
32
    "default": true,
33
    "description": "Cache formatter availability checks for better performance"
34
  }
35
}
36
```
37

38
#### Error Handling Settings
39

40
```json { .api }
41
{
42
  "suppressFormatterErrors": {
43
    "type": "boolean",
44
    "default": false,
45
    "description": "Suppress formatter error dialogs globally"
46
  },
47
  "suppressFormatterErrorsIFFAutoFormatOnSave": {
48
    "type": "boolean",
49
    "default": true,
50
    "description": "Suppress errors only during automatic format-on-save"
51
  }
52
}
53
```
54

55
### Default Formatter Configuration
56

57
Language-specific default formatter settings.
58

59
```json { .api }
60
{
61
  "preferences": {
62
    "type": "object",
63
    "properties": {
64
      "default_formatter": {
65
        "type": "object",
66
        "properties": {
67
          "python": {
68
            "anyOf": [
69
              { "type": "string" },
70
              { "type": "array", "items": { "type": "string" } }
71
            ],
72
            "default": ["isort", "black"]
73
          },
74
          "R": {
75
            "anyOf": [
76
              { "type": "string" },
77
              { "type": "array", "items": { "type": "string" } }
78
            ]
79
          }
80
        },
81
        "additionalProperties": true
82
      }
83
    }
84
  }
85
}
86
```
87

88
### Formatter-Specific Options
89

90
#### Black Formatter Options
91

92
```json { .api }
93
{
94
  "black": {
95
    "type": "object",
96
    "properties": {
97
      "line_length": {
98
        "type": "number",
99
        "default": 88,
100
        "description": "Maximum line length"
101
      },
102
      "string_normalization": {
103
        "type": "boolean",
104
        "default": true,
105
        "description": "Normalize string quotes"
106
      },
107
      "magic_trailing_comma": {
108
        "type": "boolean",
109
        "default": true,
110
        "description": "Use trailing commas"
111
      },
112
      "experimental_string_processing": {
113
        "type": "boolean",
114
        "default": false,
115
        "description": "Enable experimental string processing"
116
      },
117
      "preview": {
118
        "type": "boolean",
119
        "default": false,
120
        "description": "Enable preview features"
121
      }
122
    }
123
  }
124
}
125
```
126

127
#### Blue Formatter Options
128

129
```json { .api }
130
{
131
  "blue": {
132
    "type": "object",
133
    "properties": {
134
      "line_length": {
135
        "type": "number",
136
        "default": 88
137
      },
138
      "string_normalization": {
139
        "type": "boolean",
140
        "default": true
141
      }
142
    }
143
  }
144
}
145
```
146

147
#### Autopep8 Formatter Options
148

149
```json { .api }
150
{
151
  "autopep8": {
152
    "type": "object",
153
    "properties": {
154
      "max_line_length": {
155
        "type": "number",
156
        "default": 79
157
      },
158
      "aggressive": {
159
        "type": "number",
160
        "default": 0,
161
        "description": "Aggressiveness level (0-2)"
162
      }
163
    }
164
  }
165
}
166
```
167

168
#### YAPF Formatter Options
169

170
```json { .api }
171
{
172
  "yapf": {
173
    "type": "object",
174
    "properties": {
175
      "based_on_style": {
176
        "type": "string",
177
        "default": "pep8",
178
        "enum": ["pep8", "google", "chromium", "facebook"]
179
      },
180
      "column_limit": {
181
        "type": "number",
182
        "default": 79
183
      },
184
      "indent_width": {
185
        "type": "number",
186
        "default": 4
187
      }
188
    }
189
  }
190
}
191
```
192

193
#### Isort Formatter Options
194

195
```json { .api }
196
{
197
  "isort": {
198
    "type": "object",
199
    "properties": {
200
      "multi_line_output": {
201
        "type": "number",
202
        "default": 3,
203
        "description": "Multi-line output mode"
204
      },
205
      "include_trailing_comma": {
206
        "type": "boolean",
207
        "default": true
208
      },
209
      "force_grid_wrap": {
210
        "type": "number",
211
        "default": 0
212
      },
213
      "use_parentheses": {
214
        "type": "boolean",
215
        "default": true
216
      },
217
      "line_length": {
218
        "type": "number",
219
        "default": 88
220
      }
221
    }
222
  }
223
}
224
```
225

226
#### Ruff Formatter Options
227

228
```json { .api }
229
{
230
  "ruff": {
231
    "type": "object",
232
    "properties": {
233
      "line_length": {
234
        "type": "number",
235
        "default": 88
236
      },
237
      "select": {
238
        "type": "array",
239
        "items": { "type": "string" },
240
        "description": "Rule codes to enable"
241
      },
242
      "ignore": {
243
        "type": "array", 
244
        "items": { "type": "string" },
245
        "description": "Rule codes to ignore"
246
      }
247
    }
248
  }
249
}
250
```
251

252
## Usage Examples
253

254
### Complete Configuration Example
255

256
```json
257
{
258
  "formatOnSave": true,
259
  "cacheFormatters": true,
260
  "suppressFormatterErrors": false,
261
  "suppressFormatterErrorsIFFAutoFormatOnSave": true,
262
  
263
  "preferences": {
264
    "default_formatter": {
265
      "python": ["isort", "black"],
266
      "r": "formatR",
267
      "scala": "scalafmt",
268
      "rust": "rustfmt",
269
      "cpp": "astyle"
270
    }
271
  },
272
  
273
  "black": {
274
    "line_length": 88,
275
    "string_normalization": true,
276
    "magic_trailing_comma": true,
277
    "experimental_string_processing": false,
278
    "preview": false
279
  },
280
  
281
  "isort": {
282
    "multi_line_output": 3,
283
    "include_trailing_comma": true,
284
    "force_grid_wrap": 0,
285
    "use_parentheses": true,
286
    "line_length": 88,
287
    "profile": "black"
288
  },
289
  
290
  "yapf": {
291
    "based_on_style": "google",
292
    "column_limit": 100,
293
    "indent_width": 2
294
  },
295
  
296
  "ruff": {
297
    "line_length": 88,
298
    "select": ["E", "F", "W"],
299
    "ignore": ["E501"]
300
  }
301
}
302
```
303

304
### TypeScript Configuration Access
305

306
```typescript
307
import { ISettingRegistry } from '@jupyterlab/settingregistry';
308

309
// In the extension class
310
private async setupSettings() {
311
  const settings = await this.settingRegistry.load('jupyterlab_code_formatter:settings');
312
  
313
  const onSettingsUpdated = (jsettings: ISettingRegistry.ISettings) => {
314
    this.config = jsettings.composite;
315
  };
316
  
317
  settings.changed.connect(onSettingsUpdated);
318
  onSettingsUpdated(settings);
319
}
320

321
// Access configuration values
322
if (this.config.formatOnSave) {
323
  // Perform format on save
324
}
325

326
const blackOptions = this.config.black || {};
327
const defaultFormatters = this.config.preferences?.default_formatter?.python || [];
328
```
329

330
### Python Backend Configuration Usage
331

332
```python
333
# Configuration is passed from frontend to backend via HTTP API
334
def format_code(self, code: str, notebook: bool, **options) -> str:
335
    # Options contain formatter-specific configuration
336
    line_length = options.get('line_length', 88)
337
    string_normalization = options.get('string_normalization', True)
338
    
339
    # Use options to configure formatter
340
    black_mode = black.FileMode(
341
        line_length=line_length,
342
        string_normalization=string_normalization,
343
        **options
344
    )
345
    
346
    return black.format_str(code, mode=black_mode)
347
```
348

349
## Settings Integration
350

351
### JupyterLab Settings System
352

353
The extension integrates with JupyterLab's settings system:
354

355
- **Settings Registry**: Uses `ISettingRegistry` service
356
- **Schema Validation**: Automatic validation against JSON schema
357
- **Live Updates**: Settings changes trigger immediate updates
358
- **Persistence**: Settings saved automatically across sessions
359
- **UI Integration**: Settings accessible through JupyterLab settings editor
360

361
### Settings UI
362

363
Users can modify settings through:
364

365
1. **Settings Menu**: JupyterLab → Settings → Advanced Settings Editor
366
2. **Settings Panel**: Dedicated "Jupyterlab Code Formatter" section
367
3. **JSON Editor**: Direct JSON editing with schema validation
368
4. **Form Interface**: Auto-generated form fields from schema
369

370
### Default Values
371

372
The extension provides sensible defaults:
373

374
- **formatOnSave**: `false` (user must opt-in)
375
- **cacheFormatters**: `true` (performance optimization)
376
- **suppressFormatterErrors**: `false` (show errors by default)
377
- **Default Formatters**: Python uses `["isort", "black"]`
378
- **Formatter Options**: Use tool defaults (e.g., Black line length 88)
379

380
## Language-Specific Configuration
381

382
### Python Configuration
383

384
```json
385
{
386
  "preferences": {
387
    "default_formatter": {
388
      "python": ["isort", "black"]  // Multiple formatters in order
389
    }
390
  },
391
  "black": { "line_length": 88 },
392
  "isort": { "profile": "black" }
393
}
394
```
395

396
### R Configuration
397

398
```json
399
{
400
  "preferences": {
401
    "default_formatter": {
402
      "R": "styler"  // Single formatter
403
    }
404
  },
405
  "styler": {
406
    "scope": "tokens",
407
    "indent_by": 2
408
  }
409
}
410
```
411

412
### Multi-Language Configuration
413

414
```json
415
{
416
  "preferences": {
417
    "default_formatter": {
418
      "python": ["isort", "black"],
419
      "r": "formatR", 
420
      "scala": "scalafmt",
421
      "rust": "rustfmt",
422
      "cpp": "astyle"
423
    }
424
  }
425
}
426
```
427

428
## Error Handling Configuration
429

430
### Error Suppression Strategies
431

432
1. **Show All Errors**: Default behavior for manual formatting
433
2. **Suppress Auto-Format Errors**: Hide errors during format-on-save
434
3. **Suppress All Errors**: Hide all formatter errors (not recommended)
435

436
### Configuration Examples
437

438
```json
439
{
440
  // Show all errors (default)
441
  "suppressFormatterErrors": false,
442
  "suppressFormatterErrorsIFFAutoFormatOnSave": false,
443
  
444
  // Suppress errors only during auto-format (recommended)
445
  "suppressFormatterErrors": false,
446
  "suppressFormatterErrorsIFFAutoFormatOnSave": true,
447
  
448
  // Suppress all errors (not recommended)
449
  "suppressFormatterErrors": true,
450
  "suppressFormatterErrorsIFFAutoFormatOnSave": true
451
}
452
```
453

454
## Performance Configuration
455

456
### Caching Options
457

458
```json
459
{
460
  "cacheFormatters": true  // Cache formatter availability checks
461
}
462
```
463

464
Benefits of caching:
465
- **Faster Startup**: Reduced initialization time
466
- **Better Performance**: Avoid repeated dependency checks
467
- **Improved UX**: Faster menu updates and command execution
468

469
### Format-on-Save Performance
470

471
```json
472
{
473
  "formatOnSave": true,
474
  "suppressFormatterErrorsIFFAutoFormatOnSave": true  // Avoid error dialogs during save
475
}
476
```
477

478
This configuration enables automatic formatting while preventing disruptive error dialogs during the save process.