0
# Configuration System
1
2
Plover's configuration system provides comprehensive settings management with file persistence, validation, and runtime updates. It supports all aspects of stenographic operation including machine settings, dictionary management, output control, and GUI preferences.
3
4
## Capabilities
5
6
### Configuration Management
7
8
Core configuration class providing access to all Plover settings with automatic persistence and validation.
9
10
```python { .api }
11
class Config:
12
"""Configuration management with file persistence."""
13
14
def __init__(self, path: str = None):
15
"""
16
Initialize configuration.
17
18
Args:
19
path: Path to configuration file, uses default if None
20
21
Creates configuration instance and loads from file if it exists.
22
"""
23
24
def load(self) -> None:
25
"""
26
Load configuration from file.
27
28
Reads configuration from the specified file path,
29
applying defaults for any missing values.
30
"""
31
32
def save(self) -> None:
33
"""
34
Save configuration to file.
35
36
Writes current configuration state to file,
37
creating directories as needed.
38
"""
39
40
def clear(self) -> None:
41
"""
42
Clear all configuration values.
43
44
Resets configuration to empty state,
45
requiring reload or manual setting of values.
46
"""
47
48
def __getitem__(self, key: str):
49
"""
50
Get configuration value.
51
52
Args:
53
key: Configuration key to retrieve
54
55
Returns:
56
Value associated with the key
57
58
Raises:
59
KeyError: If key not found
60
"""
61
62
def __setitem__(self, key: str, value) -> None:
63
"""
64
Set configuration value.
65
66
Args:
67
key: Configuration key to set
68
value: Value to associate with key
69
70
Updates configuration immediately.
71
"""
72
73
def as_dict(self) -> dict:
74
"""
75
Get configuration as dictionary.
76
77
Returns:
78
Complete configuration as dictionary
79
80
Useful for serialization or bulk operations.
81
"""
82
83
def update(self, **kwargs) -> None:
84
"""
85
Update multiple configuration values.
86
87
Args:
88
**kwargs: Key-value pairs to update
89
90
Efficiently updates multiple settings at once.
91
"""
92
```
93
94
### Dictionary Configuration
95
96
Specialized configuration for individual dictionary entries with path management and state control.
97
98
```python { .api }
99
class DictionaryConfig:
100
"""Configuration for individual dictionary entries."""
101
102
def __new__(cls, path: str, enabled: bool = True) -> 'DictionaryConfig':
103
"""
104
Create dictionary configuration.
105
106
Args:
107
path: Path to dictionary file
108
enabled: Whether dictionary is enabled for lookup
109
110
Returns:
111
DictionaryConfig instance
112
113
Creates named tuple-based configuration for dictionary.
114
"""
115
116
@property
117
def short_path(self) -> str:
118
"""
119
Get shortened path for display.
120
121
Returns:
122
Abbreviated path suitable for UI display
123
124
Removes common prefixes and shortens long paths.
125
"""
126
127
def to_dict(self) -> dict:
128
"""
129
Convert to dictionary representation.
130
131
Returns:
132
Dictionary with 'path' and 'enabled' keys
133
134
Useful for serialization and API consistency.
135
"""
136
137
def replace(self, **kwargs) -> 'DictionaryConfig':
138
"""
139
Create copy with specified changes.
140
141
Args:
142
**kwargs: Fields to change (path, enabled)
143
144
Returns:
145
New DictionaryConfig with changes applied
146
147
Immutable update pattern for configuration changes.
148
"""
149
150
@staticmethod
151
def from_dict(d: dict) -> 'DictionaryConfig':
152
"""
153
Create from dictionary representation.
154
155
Args:
156
d: Dictionary with 'path' and optionally 'enabled' keys
157
158
Returns:
159
DictionaryConfig instance
160
161
Reconstructs configuration from serialized form.
162
"""
163
```
164
165
## Configuration Categories
166
167
### Output Control Settings
168
169
Controls stenographic text output behavior and formatting preferences.
170
171
**Available Settings:**
172
- `space_placement`: Where spaces are placed around words ('Before Output', 'After Output')
173
- `start_attached`: Whether to start with attached output mode
174
- `start_capitalized`: Whether to start with capitalized output mode
175
- `undo_levels`: Number of undo levels to maintain (integer)
176
- `time_between_key_presses`: Timing delay between key presses in milliseconds
177
- `keyboard_layout`: Physical keyboard layout for key mapping
178
179
### Logging Configuration
180
181
Controls diagnostic logging and stroke recording capabilities.
182
183
**Available Settings:**
184
- `log_file_name`: Path to log file for diagnostic output
185
- `enable_stroke_logging`: Whether to log stenographic strokes
186
- `enable_translation_logging`: Whether to log translation results
187
188
### GUI Preferences
189
190
Controls graphical user interface behavior and appearance.
191
192
**Available Settings:**
193
- `start_minimized`: Whether to start application minimized
194
- `show_stroke_display`: Whether to show stroke display window
195
- `show_suggestions_display`: Whether to show suggestions display
196
- `translation_frame_opacity`: Opacity level for translation display (0.0-1.0)
197
198
### Machine Configuration
199
200
Controls stenotype machine connection and communication settings.
201
202
**Available Settings:**
203
- `auto_start`: Whether to automatically start machine on launch
204
- `machine_type`: Type of stenotype machine to use
205
- `machine_specific_options`: Dictionary of machine-specific configuration options
206
207
### System Settings
208
209
Controls stenotype system definitions and key mapping.
210
211
**Available Settings:**
212
- `system_name`: Name of stenotype system to use
213
- `system_keymap`: Key mapping configuration for the selected system
214
215
### Dictionary Management
216
217
Controls dictionary loading, precedence, and management.
218
219
**Available Settings:**
220
- `dictionaries`: List of DictionaryConfig objects defining loaded dictionaries
221
222
### Plugin Configuration
223
224
Controls extension and plugin behavior.
225
226
**Available Settings:**
227
- `enabled_extensions`: List of extension names to enable on startup
228
229
## Usage Examples
230
231
```python
232
from plover.config import Config, DictionaryConfig
233
from plover.oslayer.config import CONFIG_FILE
234
235
# Create and load configuration
236
config = Config(CONFIG_FILE)
237
config.load()
238
239
# Get configuration values
240
machine_type = config['machine_type']
241
auto_start = config['auto_start']
242
dictionaries = config['dictionaries']
243
244
# Set configuration values
245
config['machine_type'] = 'Keyboard'
246
config['auto_start'] = True
247
config['undo_levels'] = 50
248
249
# Update multiple values at once
250
config.update(
251
start_minimized=False,
252
show_stroke_display=True,
253
translation_frame_opacity=0.8
254
)
255
256
# Work with dictionary configuration
257
dict_config = DictionaryConfig('/path/to/dict.json', enabled=True)
258
print(dict_config.short_path)
259
260
# Convert to dictionary
261
dict_data = dict_config.to_dict()
262
# Result: {'path': '/path/to/dict.json', 'enabled': True}
263
264
# Create from dictionary
265
new_dict_config = DictionaryConfig.from_dict({
266
'path': '/another/dict.json',
267
'enabled': False
268
})
269
270
# Update dictionary configuration
271
updated_config = dict_config.replace(enabled=False)
272
273
# Manage dictionary list
274
current_dicts = config['dictionaries']
275
new_dict = DictionaryConfig('/new/dictionary.json')
276
config['dictionaries'] = current_dicts + [new_dict]
277
278
# Save configuration
279
config.save()
280
281
# Get complete configuration
282
all_settings = config.as_dict()
283
```
284
285
## Configuration File Format
286
287
Plover stores configuration in JSON format with the following structure:
288
289
```json
290
{
291
"machine_type": "Keyboard",
292
"auto_start": true,
293
"start_minimized": false,
294
"undo_levels": 100,
295
"time_between_key_presses": 0.0,
296
"space_placement": "Before Output",
297
"start_attached": false,
298
"start_capitalized": false,
299
"keyboard_layout": "QWERTY",
300
"log_file_name": "plover.log",
301
"enable_stroke_logging": true,
302
"enable_translation_logging": true,
303
"show_stroke_display": false,
304
"show_suggestions_display": false,
305
"translation_frame_opacity": 0.8,
306
"system_name": "English Stenotype",
307
"system_keymap": {},
308
"machine_specific_options": {},
309
"dictionaries": [
310
{
311
"path": "main.json",
312
"enabled": true
313
},
314
{
315
"path": "user.json",
316
"enabled": true
317
}
318
],
319
"enabled_extensions": []
320
}
321
```
322
323
## Configuration Paths
324
325
### Default Configuration Location
326
327
Configuration files are stored in platform-specific locations:
328
329
- **Windows**: `%APPDATA%/plover/plover.cfg`
330
- **macOS**: `~/Library/Application Support/plover/plover.cfg`
331
- **Linux**: `~/.config/plover/plover.cfg`
332
333
### Dictionary Paths
334
335
Dictionary paths in configuration can be:
336
337
- **Absolute paths**: Complete file system paths
338
- **Relative paths**: Relative to configuration directory
339
- **Resource paths**: Package resource references
340
341
## Validation and Defaults
342
343
### Type Validation
344
345
Configuration values are validated for correct types:
346
347
- Strings for paths and names
348
- Booleans for on/off settings
349
- Integers for numeric limits
350
- Floats for timing and opacity values
351
- Lists for collections like dictionaries and extensions
352
353
### Default Values
354
355
Missing configuration values are populated with sensible defaults:
356
357
- Machine type defaults to 'Keyboard'
358
- Undo levels default to 100
359
- Auto-start defaults to True
360
- GUI displays default to False
361
- Opacity defaults to 0.8
362
363
### Configuration Migration
364
365
Plover automatically migrates older configuration formats to current schema, preserving user settings while adding new options with defaults.
366
367
## Types
368
369
```python { .api }
370
from typing import Dict, List, Union, Optional, Any
371
from pathlib import Path
372
373
ConfigValue = Union[str, int, bool, float, List, Dict]
374
ConfigDict = Dict[str, ConfigValue]
375
ConfigPath = Union[str, Path]
376
377
DictionaryConfigDict = Dict[str, Union[str, bool]]
378
DictionaryConfigList = List[DictionaryConfig]
379
380
MachineOptions = Dict[str, Any]
381
SystemKeymap = Dict[str, str]
382
ExtensionList = List[str]
383
```