refactor: rewrote config_file.py (better handling and transormation of config values), moved exceptions to a dedicated file, added missing config entries to README

Author: mdevolde

README.md

@@ -209,7 +209,7 @@ tool = language_tool_python.LanguageTool('en-US', config={ 'maxTextLength': 100
 
 ### Full list of configuration options
 
-Here's a full list of configuration options. See the LanguageTool [HTTPServerConfig](https://languagetool.org/development/api/org/languagetool/server/HTTPServerConfig.html) documentation for details.
+Here's a full list of configuration options:
 
 ```
 'maxTextLength' - maximum text length, longer texts will cause an error (optional)
@@ -240,6 +240,18 @@ Here's a full list of configuration options. See the LanguageTool [HTTPServerCon
 'maxPipelinePoolSize' - cache size if 'pipelineCaching' is set
 'pipelineExpireTimeInSeconds' - time after which pipeline cache items expire
 'pipelinePrewarming' - set to 'true' to fill pipeline cache on start (can slow down start a lot)
+'trustXForwardForHeader' - set this to 'true' if you run the server behind a reverse proxy and want the
+                           request limit to work on the original IP addresses provided by the 'X-forwarded-for' HTTP header,
+                           usually set by the proxy
+'suggestionsEnabled' - if suggestions should be generated for spell check errors (optional, default: true)
+
+Spellcheck-only languages: You can add simple spellcheck-only support for languages that LT doesn't
+                           support by defining two optional properties:
+  'lang-xx' - set name of the language, use language code instead of 'xx', e.g. lang-tr=Turkish
+  'lang-xx-dictPath' - absolute path to the hunspell .dic file, use language code instead of 'xx', e.g.
+                       lang-tr-dictPath=/path/to/tr.dic. Note that the same directory also needs to
+                       contain a common_words.txt file with the most common 10,000 words (used for
+                       better language detection)
 ```
 
 ## Installation

language_tool_python/__init__.py

@@ -6,9 +6,10 @@
     "LanguageTag",
     "Match",
     "utils",
+    "exceptions",
 ]
 
-from . import utils
+from . import exceptions, utils
 from .language_tag import LanguageTag
 from .match import Match
 from .server import LanguageTool, LanguageToolPublicAPI

language_tool_python/__main__.py

@@ -9,8 +9,8 @@
 
 import toml
 
+from .exceptions import LanguageToolError
 from .server import LanguageTool
-from .utils import LanguageToolError
 
 try:
     __version__ = version("language_tool_python")

language_tool_python/config_file.py

@@ -3,36 +3,133 @@
 import atexit
 import os
 import tempfile
-from typing import Any, Dict
-
-# Allowed configuration keys for LanguageTool.
-ALLOWED_CONFIG_KEYS = {
-    "maxTextLength",
-    "maxTextHardLength",
-    "maxCheckTimeMillis",
-    "maxErrorsPerWordRate",
-    "maxSpellingSuggestions",
-    "maxCheckThreads",
-    "cacheSize",
-    "cacheTTLSeconds",
-    "requestLimit",
-    "requestLimitInBytes",
-    "timeoutRequestLimit",
-    "requestLimitPeriodInSeconds",
-    "languageModel",
-    "fasttextModel",
-    "fasttextBinary",
-    "maxWorkQueueSize",
-    "rulesFile",
-    "blockedReferrers",
-    "premiumOnly",
-    "disabledRuleIds",
-    "pipelineCaching",
-    "maxPipelinePoolSize",
-    "pipelineExpireTimeInSeconds",
-    "pipelinePrewarming",
-    "trustXForwardForHeader",
-    "suggestionsEnabled",
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, Optional, Union
+
+from .exceptions import PathError
+
+
+@dataclass(frozen=True)
+class OptionSpec:
+    """
+    Specification for a configuration option.
+
+    This class defines the structure and behavior of a configuration option,
+    including its type constraints, encoding mechanism, and optional validation.
+
+    Attributes:
+        py_types (Union[type, tuple[type, ...]]): The Python type(s) that this option accepts.
+        encoder (Callable[[Any], str]): A callable that converts the option value to its string representation.
+        validator (Optional[Callable[[Any], None]]): An optional callable that validates the option value.
+
+    .. note::
+    This class is frozen (immutable) to ensure configuration specifications
+    remain constant throughout the application lifecycle.
+    """
+
+    py_types: Union[type, tuple[type, ...]]
+    encoder: Callable[[Any], str]
+    validator: Optional[Callable[[Any], None]] = None
+
+
+def _bool_encoder(v: Any) -> str:
+    """
+    Encode a value as a lowercase boolean string.
+
+    Converts any value to a boolean and returns its string representation
+    in lowercase format ('true' or 'false').
+
+    :param v: The value to be converted to a boolean string.
+    :type v: Any
+    :return: A lowercase string representation of the boolean value ('true' or 'false').
+    :rtype: str
+    """
+    return str(bool(v)).lower()
+
+
+def _comma_list_encoder(v: Any) -> str:
+    """
+    Encode a value as a comma-separated list string.
+
+    Converts a value into a string representation suitable for comma-separated
+    list configuration options. If the input is already a string, it is returned
+    as-is. If it's an iterable, its elements are converted to strings and joined
+    with commas.
+
+    :param v: The value to encode. Can be a string or an iterable of values.
+    :type v: Any
+    :return: A comma-separated string representation of the input value.
+    :rtype: str
+    :raises TypeError: If the input is neither a string nor an iterable.
+    """
+    if isinstance(v, str):
+        return v
+    if isinstance(v, Iterable):
+        return ",".join(str(x) for x in v)
+    raise TypeError("expected string or iterable for comma-list option")
+
+
+def _path_encoder(v: Any) -> str:
+    """
+    Encode a path value to a string.
+    Converts the input to a Path object, then to a string, and escapes all
+    backslashes by doubling them. This is useful for windows file paths and
+    other contexts where backslashes need to be escaped. (because they will
+    be used by LT java binary)
+
+    :param v: The path value to encode. Can be any type that Path accepts
+        (str, Path, etc.).
+    :type v: Any
+    :return: The path as a string with escaped backslashes (e.g., "C:\\\\Users\\\\file").
+    :rtype: str
+    """
+    return str(Path(v)).replace("\\", "\\\\")
+
+
+def _path_validator(v: Any) -> None:
+    """
+    Validate that a given path exists and is a file.
+
+    :param v: The path to validate, which will be converted to a Path object
+    :type v: Any
+    :raises PathError: If the path does not exist
+    :raises PathError: If the path exists but is not a file
+    """
+    p = Path(v)
+    if not p.exists():
+        raise PathError(f"path does not exist: {p}")
+    if not p.is_file():
+        raise PathError(f"path is not a file: {p}")
+
+
+CONFIG_SCHEMA: Dict[str, OptionSpec] = {
+    "maxTextLength": OptionSpec(int, lambda v: str(int(v))),
+    "maxTextHardLength": OptionSpec(int, lambda v: str(int(v))),
+    "maxCheckTimeMillis": OptionSpec(int, lambda v: str(int(v))),
+    "maxErrorsPerWordRate": OptionSpec((int, float), lambda v: str(float(v))),
+    "maxSpellingSuggestions": OptionSpec(int, lambda v: str(int(v))),
+    "maxCheckThreads": OptionSpec(int, lambda v: str(int(v))),
+    "cacheSize": OptionSpec(int, lambda v: str(int(v))),
+    "cacheTTLSeconds": OptionSpec(int, lambda v: str(int(v))),
+    "requestLimit": OptionSpec(int, lambda v: str(int(v))),
+    "requestLimitInBytes": OptionSpec(int, lambda v: str(int(v))),
+    "timeoutRequestLimit": OptionSpec(int, lambda v: str(int(v))),
+    "requestLimitPeriodInSeconds": OptionSpec(int, lambda v: str(int(v))),
+    "languageModel": OptionSpec((str, Path), _path_encoder, _path_validator),
+    "fasttextModel": OptionSpec((str, Path), _path_encoder, _path_validator),
+    "fasttextBinary": OptionSpec((str, Path), _path_encoder, _path_validator),
+    "maxWorkQueueSize": OptionSpec(int, lambda v: str(int(v))),
+    "rulesFile": OptionSpec((str, Path), _path_encoder, _path_validator),
+    "blockedReferrers": OptionSpec((str, list, tuple, set), _comma_list_encoder),
+    "premiumOnly": OptionSpec((bool, int), _bool_encoder),
+    "disabledRuleIds": OptionSpec((str, list, tuple, set), _comma_list_encoder),
+    "pipelineCaching": OptionSpec((bool, int), _bool_encoder),
+    "maxPipelinePoolSize": OptionSpec(int, lambda v: str(int(v))),
+    "pipelineExpireTimeInSeconds": OptionSpec(int, lambda v: str(int(v))),
+    "pipelinePrewarming": OptionSpec((bool, int), _bool_encoder),
+    "trustXForwardForHeader": OptionSpec((bool, int), _bool_encoder),
+    "suggestionsEnabled": OptionSpec((bool, int), _bool_encoder),
 }
 
 
@@ -53,23 +150,50 @@ def _is_lang_key(key: str) -> bool:
         return False
 
     parts = key.split("-")
-    return (len(parts) == 2 and len(parts[1]) > 0) or (
-        len(parts) == 3 and len(parts[1]) > 0 and parts[2] == "dictPath"
+    return (len(parts) == 2 and len(parts[1]) > 0) or (  # lang-<code>
+        len(parts) == 3
+        and len(parts[1]) > 0
+        and parts[2] == "dictPath"  # lang-<code>-dictPath
     )
 
 
-def _validate_config_keys(config: Dict[str, Any]) -> None:
+def _encode_config(config: Dict[str, Any]) -> Dict[str, str]:
     """
-    Validate that all keys in the configuration dictionary are allowed.
+    Encode configuration dictionary values to their string representations.
+    This function converts a configuration dictionary into a format suitable for
+    serialization by encoding each value according to its corresponding schema
+    specification.
 
-    :param config: Dictionary containing configuration keys and values.
+    :param config: A dictionary containing configuration keys and values to be encoded.
     :type config: Dict[str, Any]
-    :raises ValueError: If a key is found that is not in ALLOWED_CONFIG_KEYS and is not a language key.
+    :return: A dictionary with the same keys but with all values encoded as strings.
+    :rtype: Dict[str, str]
+    :raises ValueError: If a key in the config is not found in the CONFIG_SCHEMA and
+                       is not a language key.
+    :raises TypeError: If a value's type does not match the expected type(s) defined
+                      in the CONFIG_SCHEMA specification.
     """
-    for key in config:
-        if key not in ALLOWED_CONFIG_KEYS and not _is_lang_key(key):
+    encoded: Dict[str, str] = {}
+    for key, value in config.items():
+        if _is_lang_key(key) and key.count("-") == 1:  # lang-<code>
+            encoded[key] = str(value)
+            continue
+        if _is_lang_key(key) and key.count("-") == 2:  # lang-<code>-dictPath
+            _path_validator(value)
+            encoded[key] = _path_encoder(value)
+            continue
+
+        spec = CONFIG_SCHEMA.get(key)
+        if spec is None:
             raise ValueError(f"unexpected key in config: {key}")
 
+        if not isinstance(value, spec.py_types):
+            raise TypeError(f"invalid type for {key}: {type(value).__name__}")
+        if spec.validator is not None:
+            spec.validator(value)
+        encoded[key] = spec.encoder(value)
+    return encoded
+
 
 class LanguageToolConfig:
     """
@@ -92,24 +216,8 @@ def __init__(self, config: Dict[str, Any]):
         """
         if not config:
             raise ValueError("config cannot be empty")
-        _validate_config_keys(config)
-
-        self.config = config
-
-        if "disabledRuleIds" in self.config:
-            self.config["disabledRuleIds"] = ",".join(self.config["disabledRuleIds"])
-        if "blockedReferrers" in self.config:
-            self.config["blockedReferrers"] = ",".join(self.config["blockedReferrers"])
-        for key in [
-            "pipelineCaching",
-            "premiumOnly",
-            "pipelinePrewarming",
-            "trustXForwardForHeader",
-            "suggestionsEnabled",
-        ]:
-            if key in self.config:
-                self.config[key] = str(bool(self.config[key])).lower()
 
+        self.config = _encode_config(config)
         self.path = self._create_temp_file()
 
     def _create_temp_file(self) -> str:

language_tool_python/download_lt.py

@@ -14,9 +14,9 @@
 import requests
 import tqdm
 
+from .exceptions import PathError
 from .utils import (
     LTP_JAR_DIR_PATH_ENV_VAR,
-    PathError,
     find_existing_language_tool_downloads,
     get_language_tool_download_path,
 )

language_tool_python/exceptions.py

@@ -0,0 +1,49 @@
+class LanguageToolError(Exception):
+    """
+    Exception raised for errors in the LanguageTool library.
+    This is a generic exception that can be used to indicate various types of
+    errors encountered while using the LanguageTool library.
+    """
+
+    pass
+
+
+class ServerError(LanguageToolError):
+    """
+    Exception raised for errors that occur when interacting with the LanguageTool server.
+    This exception is a subclass of `LanguageToolError` and is used to indicate
+    issues such as server startup failures.
+    """
+
+    pass
+
+
+class JavaError(LanguageToolError):
+    """
+    Exception raised for errors related to the Java backend of LanguageTool.
+    This exception is a subclass of `LanguageToolError` and is used to indicate
+    issues that occur when interacting with Java, such as Java not being found.
+    """
+
+    pass
+
+
+class PathError(LanguageToolError):
+    """
+    Exception raised for errors in the file path used in LanguageTool.
+    This error is raised when there is an issue with the file path provided
+    to LanguageTool, such as the LanguageTool JAR file not being found,
+    or a download path not being a valid available file path.
+    """
+
+    pass
+
+
+class RateLimitError(LanguageToolError):
+    """
+    Exception raised for errors related to rate limiting in the LanguageTool server.
+    This exception is a subclass of `LanguageToolError` and is used to indicate
+    issues such as exceeding the allowed number of requests to the public API without a key.
+    """
+
+    pass

language_tool_python/server.py

@@ -16,14 +16,16 @@
 
 from .config_file import LanguageToolConfig
 from .download_lt import LTP_DOWNLOAD_VERSION, download_lt
-from .language_tag import LanguageTag
-from .match import Match
-from .utils import (
-    FAILSAFE_LANGUAGE,
+from .exceptions import (
     LanguageToolError,
     PathError,
     RateLimitError,
     ServerError,
+)
+from .language_tag import LanguageTag
+from .match import Match
+from .utils import (
+    FAILSAFE_LANGUAGE,
     correct,
     get_language_tool_directory,
     get_locale_language,