plover 5.0.0rc1__py3-none-any.whl → 5.2.0__py3-none-any.whl

plover/__init__.py

@@ -11,9 +11,11 @@ else:
     # exec from `setup.py`, package data
     # may not be available, and we don't
     # want to translate anyway.
-    _ = lambda s: s
+    def _(s):
+        return s
 
-__version__ = "5.0.0rc1"
+
+__version__ = "5.2.0"
 __copyright__ = "(C) Open Steno Project"
 __url__ = "http://www.openstenoproject.org/"
 __download_url__ = "http://www.openstenoproject.org/plover"
@@ -24,7 +26,7 @@ Developers:
 
 Joshua Lifton
 Hesky Fisher
-Ted Morin
+Thea Morin
 Benoit Pierre
 Sammi Ta
 Martin Koerner

plover/config.py

@@ -1,12 +1,14 @@
 # Copyright (c) 2010-2011 Joshua Harlan Lifton.
 # See LICENSE.txt for details.
 
-"""Configuration management."""
+"""This modules handles reading and writing Plover's configuration files, as well
+as updating the configuration on-the-fly while Plover is running."""
 
 from collections import ChainMap, namedtuple, OrderedDict
 import configparser
 import json
 import re
+from typing import Any, Dict
 
 from plover.exception import InvalidConfigurationError
 from plover.machine.keymap import Keymap
@@ -17,6 +19,7 @@ from plover import log
 
 
 # General configuration sections, options and defaults.
+APPEARANCE_CONFIG_SECTION = "Appearance"
 MACHINE_CONFIG_SECTION = "Machine Configuration"
 
 LEGACY_DICTIONARY_CONFIG_SECTION = "Dictionary Configuration"
@@ -36,14 +39,23 @@ SYSTEM_KEYMAP_OPTION = "keymap[%s]"
 
 
 class DictionaryConfig(namedtuple("DictionaryConfig", "path enabled")):
+    """Represents the configuration for one dictionary.
+
+    Attributes:
+        path (str): The fully qualified path to the dictionary file.
+        enabled (bool): Whether the dictionary is enabled.
+    """
+
     def __new__(cls, path, enabled=True):
         return super().__new__(cls, expand_path(path), enabled)
 
     @property
-    def short_path(self):
+    def short_path(self) -> str:
+        """The shortened path to the dictionary file. This is automatically calculated from :attr:`path`."""
         return shorten_path(self.path)
 
-    def to_dict(self):
+    def to_dict(self) -> Dict[str, Any]:
+        """Returns the ``dict`` representation of the dictionary configuration."""
         # Note: do not use _asdict because of
         # https://bugs.python.org/issue24931
         return {
@@ -51,11 +63,13 @@ class DictionaryConfig(namedtuple("DictionaryConfig", "path enabled")):
             "enabled": self.enabled,
         }
 
-    def replace(self, **kwargs):
+    def replace(self, **kwargs) -> "DictionaryConfig":
+        """Replaces the values of :attr:`path` and :attr:`enabled` with those in ``kwargs``."""
         return self._replace(**kwargs)
 
     @staticmethod
-    def from_dict(d):
+    def from_dict(d: Dict[str, Any]) -> "DictionaryConfig":
+        """Returns a :class:`DictionaryConfig` constructed from its ``dict`` representation."""
         return DictionaryConfig(**d)
 
     def __repr__(self):
@@ -73,6 +87,11 @@ ConfigOption = namedtuple(
 
 
 class InvalidConfigOption(ValueError):
+    """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.
+    """
+
     def __init__(self, raw_value, fixed_value, message=None):
         super().__init__(raw_value)
         self.raw_value = raw_value
@@ -368,14 +387,22 @@ def dictionaries_option():
 
 
 class Config:
-    def __init__(self, path=None):
+    """An object containing the entire Plover configuration. The config object
+    maintains a cache for any changes that are made while Plover is running.
+    """
+
+    def __init__(self, path=None) -> None:
         self._config = None
         self._cache = {}
         # A convenient place for other code to store a file name.
         self.path = path
         self.clear()
 
-    def load(self):
+    def load(self) -> None:
+        """Reads and parses the configuration from the configuration file. Raises an
+        :exc:`InvalidConfigurationError<plover.exception.InvalidConfigurationError>`
+        if the configuration could not be parsed correctly.
+        """
         self.clear()
         with open(self.path, encoding="utf-8") as fp:
             try:
@@ -383,11 +410,13 @@ class Config:
             except configparser.Error as e:
                 raise InvalidConfigurationError(str(e))
 
-    def clear(self):
+    def clear(self) -> None:
+        """Clears the configuration and returns to the base state."""
         self._config = configparser.RawConfigParser()
         self._cache.clear()
 
-    def save(self):
+    def save(self) -> None:
+        """Writes the current state of the configuration to the configuration file."""
         with resource_update(self.path) as temp_path:
             with open(temp_path, mode="w", encoding="utf-8") as fp:
                 self._config.write(fp)
@@ -427,7 +456,7 @@ class Config:
             ),
             choice_option(
                 "keyboard_layout",
-                ("qwerty", "qwertz", "colemak", "colemak-dh", "dvorak"),
+                ("qwerty", "qwertz", "colemak", "colemak-dh", "dvorak", "wayland-auto"),
                 OUTPUT_CONFIG_SECTION,
             ),
             # Logging.
@@ -439,6 +468,13 @@ class Config:
             ),
             boolean_option("enable_stroke_logging", False, LOGGING_CONFIG_SECTION),
             boolean_option("enable_translation_logging", False, LOGGING_CONFIG_SECTION),
+            # Appearance.
+            choice_option(
+                "appearance_mode",
+                ("system", "light", "dark"),
+                APPEARANCE_CONFIG_SECTION,
+                "mode",
+            ),
             # GUI.
             boolean_option("start_minimized", False, "Startup", "Start Minimized"),
             boolean_option("show_stroke_display", False, "Stroke Display", "show"),
@@ -471,7 +507,10 @@ class Config:
             key = opt.full_key(self, key)
         return key, opt
 
-    def __getitem__(self, key):
+    def __getitem__(self, key: str) -> Any:
+        """Returns the value of the specified ``key`` in the cache, or in the
+        full configuration if not available.
+        """
         key, opt = self._lookup(key)
         if key in self._cache:
             return self._cache[key]
@@ -485,16 +524,21 @@ class Config:
         self._cache[key] = value
         return value
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Sets the property ``key`` in the configuration to the specified value."""
         key, opt = self._lookup(key)
         value = opt.validate(self._config, key, value)
         opt.setter(self, key, value)
         self._cache[key] = value
 
-    def as_dict(self):
+    def as_dict(self) -> Dict[str, Any]:
+        """Returns the ``dict`` representation of the current state of the
+        configuration.
+        """
         return {opt.name: self[opt.name] for opt in self._OPTIONS.values()}
 
-    def update(self, **kwargs):
+    def update(self, **kwargs) -> None:
+        """Update the cache to reflect the contents of the full configuration."""
         new_settings = []
         new_config = ChainMap({}, self)
         for opt in self._OPTIONS.values():

plover/dictionary/loading_manager.py

@@ -7,13 +7,19 @@ import threading
 import time
 
 from plover.dictionary.base import load_dictionary
-from plover.exception import DictionaryLoaderException
 from plover.resource import resource_timestamp
 from plover import log
 
 
 class DictionaryLoadingManager:
-    def __init__(self):
+    def __init__(self, state_change_callback):
+        """
+        Parameters:
+        state_change_callback -- A function that will be called when any dictionary is loaded
+            with two parameters: the filename and the loaded StenoDictionary object
+            (or an instance of ErroredDictionary if the load fails).
+        """
+        self._state_change_callback = state_change_callback
         self.dictionaries = {}
 
     def __len__(self):
@@ -32,7 +38,7 @@ class DictionaryLoadingManager:
         log.info(
             "%s dictionary: %s", "loading" if op is None else "reloading", filename
         )
-        op = DictionaryLoadingOperation(filename)
+        op = DictionaryLoadingOperation(filename, self._state_change_callback)
         self.dictionaries[filename] = op
         return op
 
@@ -52,7 +58,15 @@ class DictionaryLoadingManager:
 
 
 class DictionaryLoadingOperation:
-    def __init__(self, filename):
+    def __init__(self, filename, state_change_callback):
+        """
+        Parameters:
+        filename -- Path to dictionary file.
+        state_change_callback -- A function that will be called when the load is finished
+            with two parameters: the filename and the loaded StenoDictionary object
+            (or an instance of ErroredDictionary if the load fails).
+        """
+        self._state_change_callback = state_change_callback
         self.loading_thread = threading.Thread(target=self.load)
         self.filename = filename
         self.result = None
@@ -61,7 +75,7 @@ class DictionaryLoadingOperation:
     def needs_reloading(self):
         try:
             new_timestamp = resource_timestamp(self.filename)
-        except:
+        except Exception:
             # Bad resource name, permission denied, path
             # does not exist, ...
             new_timestamp = None
@@ -87,8 +101,11 @@ class DictionaryLoadingOperation:
             self.result = load_dictionary(self.filename)
         except Exception as e:
             log.debug("loading dictionary %s failed", self.filename, exc_info=True)
-            self.result = DictionaryLoaderException(self.filename, e)
+            from plover.engine import ErroredDictionary
+
+            self.result = ErroredDictionary(self.filename, e)
             self.result.timestamp = timestamp
+        self._state_change_callback(self.filename, self.result)
 
     def get(self):
         self.loading_thread.join()