This modules handles reading and writing Plover's configuration files, as well as updating the configuration on-the-fly while Plover is running.
An object containing the entire Plover configuration. The config object
maintains a cache for any changes that are made while Plover is running.
```{method} load()
Reads and parses the configuration from the configuration file.
Raises an {exc}`InvalidConfigurationError<plover.exception.InvalidConfigurationError>`
if the configuration could not be parsed correctly.
```
```{method} clear()
Clears the configuration and returns to the base state.
```
```{method} save()
Writes the current state of the configuration to the configuration file.
```
```{method} __getitem__(key: str) -> any
Returns the value of the specified `key` in the cache, or in the
full configuration if not available.
```
```{method} __setitem__(key: str, value: any)
Sets the property `key` in the configuration to the specified value.
```
```{method} as_dict() -> Dict[str, any]
Returns the `dict` representation of the current state of the
configuration.
```
```{method} update()
Update the cache to reflect the contents of the full configuration.
```
An exception raised when a configuration option has been set to an invalid
value, such as one of the wrong type. `fixed_value` is the value that
Plover is falling back on if `raw_value` can't be parsed correctly.
Represents the configuration for one dictionary.
```{attribute} path
:type: str
The fully qualified path to the dictionary file.
```
```{attribute} short_path
:type: str
The shortened path to the dictionary file. This is automatically
calculated from {attr}`path`.
```
```{attribute} enabled
:type: bool
Whether the dictionary is enabled.
```
```{staticmethod} from_dict(d: Dict[str, any]) -> DictionaryConfig
Returns a {class}`DictionaryConfig` constructed from its `dict`
representation.
```
```{method} to_dict() -> Dict[str, any]
Returns the `dict` representation of the dictionary configuration.
```
```{method} replace(**kwargs: Dict[str, any])
Replaces the values of {attr}`path` and {attr}`enabled` with those in `kwargs`.
```
(config-keys)=
Below is the list of all available configuration keys:
When writing translations, whether to add spaces before or after each
translation. Possible values are `Before Output` and `After Output`.
By default, will add spaces *before* translations.
Whether to delete the space before the translation when the initial
stroke is translated. `False` by default.
Whether to capitalize the translation when the initial stroke is
translated. ``False`` by default.
The maximum number of translations Plover is allowed to undo. 100 by default.
Each stroke that performs a translation is added onto an undo stack, and
undo strokes (such as ``*``) remove translations from this stack.
`undo_levels` defines the maximum number of translations in the stack.
The path to the stroke log file, either absolute or expressed relative to
{data}`CONFIG_DIR<plover.oslayer.config.CONFIG_DIR>`. `strokes.log` by default.
This only sets the path for stroke logs; main Plover logs are always
written to `plover.log`.
Whether to log strokes. `False` by default.
Whether to log translations. `False` by default.
Whether to hide the main window when Plover starts up. `False` by default.
Whether to show the paper tape when Plover starts up. `False` by default.
Whether to show the suggestions window when Plover starts up. `False` by default.
The opacity of the Add Translation tool, in percent. 100 by default.
The order the dictionaries are displayed in the main window.
`True` displays the highest priority dictionary at the bottom;
`False` displays it at the top. `False` by default.
The list of extensions that are enabled.
Whether to enable Plover output when it starts up. `False` by default.
The name of the currently active machine. `Keyboard` by default.
A dictionary of configuration options specific to the current machine.
Consult your machine plugin's documentation to see the available properties.
For the default machine plugins, the following options are available:
```{describe} arpeggiate
Whether to enable arpeggiate mode on the keyboard. `False` by default.
```
```{describe} port
The serial port for serial connections. No default value.
The value will most likely be different between platforms; Windows uses COM
ports, e.g. `COM3`, whereas Unix-like platforms use device paths, e.g.
`/dev/cu.usbmodem14403` or `/dev/ttyACM0`.
```
```{describe} baudrate
The baud rate for serial connections. 9600 by default.
```
```{describe} bytesize
The number of bits in a byte for serial connections. 8 by default.
```
```{describe} parity
The parity bit mode for serial connections, one of
`N` (none), `O` (odd), `E` (even), `M` (mark) or `S` (space).
`N` by default.
```
```{describe} stopbits
The number of stop bits for serial connections. 1 by default.
```
```{describe} timeout
The read timeout for serial connections in seconds, may be ``None`` to
disable read timeouts altogether. 2.0 (2 seconds) by default.
```
```{describe} xonxoff
Whether to use XON/XOFF flow control for serial connections.
`False` by default.
```
```{describe} rtscts
Whether to use RTS/CTS flow control for serial connections.
`False` by default.
```
The name of the current steno system. This is the same system that
{mod}`plover.system` refers to. ``English Stenotype`` by default.
A {class}`Keymap<plover.machine.keymap.Keymap>` mapping between machine
keys and steno keys in the current steno system.
If the system defines a keymap in {data}`KEYMAPS<plover.system.KEYMAPS>`
for the current machine type, that will be the default value; otherwise,
the machine may define a
{attr}`KEYMAP_MACHINE_TYPE<plover.machine.base.StenotypeBase.KEYMAP_MACHINE_TYPE>`
that describes a similar machine to fall back on. If that is not available
either, the default value is an empty keymap.
A list of {class}`DictionaryConfig` representing the list of dictionaries
Plover uses to translate strokes for the current steno system. The
dictionaries should be listed in order of decreasing priority.