tessl/pypi-plover

Open Source Stenography Software providing real-time stenographic typing, machine support, and plugin architecture.

—

Pending

Overview

Eval results

Files

Configuration System

Name: tessl/pypi-plover
Author: tessl

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.

Capabilities

Configuration Management

Core configuration class providing access to all Plover settings with automatic persistence and validation.

class Config:
    """Configuration management with file persistence."""
    
    def __init__(self, path: str = None):
        """
        Initialize configuration.
        
        Args:
            path: Path to configuration file, uses default if None
            
        Creates configuration instance and loads from file if it exists.
        """
    
    def load(self) -> None:
        """
        Load configuration from file.
        
        Reads configuration from the specified file path,
        applying defaults for any missing values.
        """
    
    def save(self) -> None:
        """
        Save configuration to file.
        
        Writes current configuration state to file,
        creating directories as needed.
        """
    
    def clear(self) -> None:
        """
        Clear all configuration values.
        
        Resets configuration to empty state,
        requiring reload or manual setting of values.
        """
    
    def __getitem__(self, key: str):
        """
        Get configuration value.
        
        Args:
            key: Configuration key to retrieve
            
        Returns:
            Value associated with the key
            
        Raises:
            KeyError: If key not found
        """
    
    def __setitem__(self, key: str, value) -> None:
        """
        Set configuration value.
        
        Args:
            key: Configuration key to set
            value: Value to associate with key
            
        Updates configuration immediately.
        """
    
    def as_dict(self) -> dict:
        """
        Get configuration as dictionary.
        
        Returns:
            Complete configuration as dictionary
            
        Useful for serialization or bulk operations.
        """
    
    def update(self, **kwargs) -> None:
        """
        Update multiple configuration values.
        
        Args:
            **kwargs: Key-value pairs to update
            
        Efficiently updates multiple settings at once.
        """

Dictionary Configuration

Specialized configuration for individual dictionary entries with path management and state control.

class DictionaryConfig:
    """Configuration for individual dictionary entries."""
    
    def __new__(cls, path: str, enabled: bool = True) -> 'DictionaryConfig':
        """
        Create dictionary configuration.
        
        Args:
            path: Path to dictionary file
            enabled: Whether dictionary is enabled for lookup
            
        Returns:
            DictionaryConfig instance
            
        Creates named tuple-based configuration for dictionary.
        """
    
    @property
    def short_path(self) -> str:
        """
        Get shortened path for display.
        
        Returns:
            Abbreviated path suitable for UI display
            
        Removes common prefixes and shortens long paths.
        """
    
    def to_dict(self) -> dict:
        """
        Convert to dictionary representation.
        
        Returns:
            Dictionary with 'path' and 'enabled' keys
            
        Useful for serialization and API consistency.
        """
    
    def replace(self, **kwargs) -> 'DictionaryConfig':
        """
        Create copy with specified changes.
        
        Args:
            **kwargs: Fields to change (path, enabled)
            
        Returns:
            New DictionaryConfig with changes applied
            
        Immutable update pattern for configuration changes.
        """
    
    @staticmethod
    def from_dict(d: dict) -> 'DictionaryConfig':
        """
        Create from dictionary representation.
        
        Args:
            d: Dictionary with 'path' and optionally 'enabled' keys
            
        Returns:
            DictionaryConfig instance
            
        Reconstructs configuration from serialized form.
        """

Configuration Categories

Output Control Settings

Controls stenographic text output behavior and formatting preferences.

Available Settings:

space_placement: Where spaces are placed around words ('Before Output', 'After Output')
start_attached: Whether to start with attached output mode
start_capitalized: Whether to start with capitalized output mode
undo_levels: Number of undo levels to maintain (integer)
time_between_key_presses: Timing delay between key presses in milliseconds
keyboard_layout: Physical keyboard layout for key mapping

Logging Configuration

Controls diagnostic logging and stroke recording capabilities.

Available Settings:

log_file_name: Path to log file for diagnostic output
enable_stroke_logging: Whether to log stenographic strokes
enable_translation_logging: Whether to log translation results

GUI Preferences

Controls graphical user interface behavior and appearance.

Available Settings:

start_minimized: Whether to start application minimized
show_stroke_display: Whether to show stroke display window
show_suggestions_display: Whether to show suggestions display
translation_frame_opacity: Opacity level for translation display (0.0-1.0)

Machine Configuration

Controls stenotype machine connection and communication settings.

Available Settings:

auto_start: Whether to automatically start machine on launch
machine_type: Type of stenotype machine to use
machine_specific_options: Dictionary of machine-specific configuration options

System Settings

Controls stenotype system definitions and key mapping.

Available Settings:

system_name: Name of stenotype system to use
system_keymap: Key mapping configuration for the selected system

Dictionary Management

Controls dictionary loading, precedence, and management.

Available Settings:

dictionaries: List of DictionaryConfig objects defining loaded dictionaries

Plugin Configuration

Controls extension and plugin behavior.

Available Settings:

enabled_extensions: List of extension names to enable on startup

Usage Examples

from plover.config import Config, DictionaryConfig
from plover.oslayer.config import CONFIG_FILE

# Create and load configuration
config = Config(CONFIG_FILE)
config.load()

# Get configuration values
machine_type = config['machine_type']
auto_start = config['auto_start']
dictionaries = config['dictionaries']

# Set configuration values
config['machine_type'] = 'Keyboard'
config['auto_start'] = True
config['undo_levels'] = 50

# Update multiple values at once
config.update(
    start_minimized=False,
    show_stroke_display=True,
    translation_frame_opacity=0.8
)

# Work with dictionary configuration
dict_config = DictionaryConfig('/path/to/dict.json', enabled=True)
print(dict_config.short_path)

# Convert to dictionary
dict_data = dict_config.to_dict()
# Result: {'path': '/path/to/dict.json', 'enabled': True}

# Create from dictionary
new_dict_config = DictionaryConfig.from_dict({
    'path': '/another/dict.json',
    'enabled': False
})

# Update dictionary configuration
updated_config = dict_config.replace(enabled=False)

# Manage dictionary list
current_dicts = config['dictionaries']
new_dict = DictionaryConfig('/new/dictionary.json')
config['dictionaries'] = current_dicts + [new_dict]

# Save configuration
config.save()

# Get complete configuration
all_settings = config.as_dict()

Configuration File Format

Plover stores configuration in JSON format with the following structure:

{
  "machine_type": "Keyboard",
  "auto_start": true,
  "start_minimized": false,
  "undo_levels": 100,
  "time_between_key_presses": 0.0,
  "space_placement": "Before Output",
  "start_attached": false,
  "start_capitalized": false,
  "keyboard_layout": "QWERTY",
  "log_file_name": "plover.log",
  "enable_stroke_logging": true,
  "enable_translation_logging": true,
  "show_stroke_display": false,
  "show_suggestions_display": false,
  "translation_frame_opacity": 0.8,
  "system_name": "English Stenotype",
  "system_keymap": {},
  "machine_specific_options": {},
  "dictionaries": [
    {
      "path": "main.json",
      "enabled": true
    },
    {
      "path": "user.json", 
      "enabled": true
    }
  ],
  "enabled_extensions": []
}

Configuration Paths

Default Configuration Location

Configuration files are stored in platform-specific locations:

Windows: %APPDATA%/plover/plover.cfg
macOS: ~/Library/Application Support/plover/plover.cfg
Linux: ~/.config/plover/plover.cfg

Dictionary Paths

Dictionary paths in configuration can be:

Absolute paths: Complete file system paths
Relative paths: Relative to configuration directory
Resource paths: Package resource references

Validation and Defaults

Type Validation

Configuration values are validated for correct types:

Strings for paths and names
Booleans for on/off settings
Integers for numeric limits
Floats for timing and opacity values
Lists for collections like dictionaries and extensions

Default Values

Missing configuration values are populated with sensible defaults:

Machine type defaults to 'Keyboard'
Undo levels default to 100
Auto-start defaults to True
GUI displays default to False
Opacity defaults to 0.8

Configuration Migration

Plover automatically migrates older configuration formats to current schema, preserving user settings while adding new options with defaults.

Types

from typing import Dict, List, Union, Optional, Any
from pathlib import Path

ConfigValue = Union[str, int, bool, float, List, Dict]
ConfigDict = Dict[str, ConfigValue]
ConfigPath = Union[str, Path]

DictionaryConfigDict = Dict[str, Union[str, bool]]
DictionaryConfigList = List[DictionaryConfig]

MachineOptions = Dict[str, Any]
SystemKeymap = Dict[str, str]
ExtensionList = List[str]

Install with Tessl CLI