Merge pull request jxmorris12#105 from mdevolde/master

Adding doc, removing unused parts, modernizing

Author: jxmorris12

language_tool_python/__init__.py

@@ -1,8 +1,3 @@
-"""LanguageTool through server mode.
-
-    migration URL: https://languagetool.org/http-api/migration.php
-"""
-
 from .language_tag import LanguageTag
 from .match import Match
 from .server import LanguageTool, LanguageToolPublicAPI

language_tool_python/__main__.py

@@ -4,20 +4,27 @@
 import locale
 import re
 import sys
-from importlib.metadata import version
+from importlib.metadata import version, PackageNotFoundError
 import toml
+from typing import Any, Optional, Set, Union
 
 from .server import LanguageTool
 from .utils import LanguageToolError
 
 try:
     __version__ = version("language_tool_python")
-except PackageNotFoundError:
+except PackageNotFoundError: # If the package is not installed in the environment, read the version from pyproject.toml
     with open("pyproject.toml", "rb") as f:
         __version__ = toml.loads(f.read().decode('utf-8'))["project"]["version"]
 
 
-def parse_args():
+def parse_args() -> argparse.Namespace:
+    """
+    Parse command line arguments.
+
+    :return: parsed arguments
+    :rtype: argparse.Namespace
+    """
     parser = argparse.ArgumentParser(
         description=__doc__.strip() if __doc__ else None,
         prog='language_tool_python')
@@ -42,7 +49,7 @@ def parse_args():
                         help='If set, additional rules will be activated.')
     parser.add_argument(
         '--version', action='version',
-        version='%(prog)s {}'.format(__version__),
+        version=f'%(prog)s {__version__}',
         help='show version')
     parser.add_argument('-a', '--apply', action='store_true',
                         help='automatically apply suggestions if available')
@@ -69,22 +76,71 @@ def parse_args():
 
 
 class RulesAction(argparse.Action):
-    def __call__(self, parser, namespace, values, option_string=None):
+    """
+    Custom argparse action to update a set of rules in the namespace.
+    This action is used to modify the set of rules stored in the argparse
+    namespace when the action is triggered. It updates the attribute specified
+    by 'self.dest' with the provided values.
+
+    Attributes:
+        dest (str): the destination attribute to update
+    """
+    def __call__(self, parser: argparse.ArgumentParser, namespace: Any, values: Any, option_string: Optional[str] = None):
+        """
+        This method is called when the action is triggered. It updates the set of rules
+        in the namespace with the provided values. The method is invoked automatically
+        by argparse when the corresponding command-line argument is encountered.
+
+        :param parser: The ArgumentParser object which contains this action.
+        :type parser: argparse.ArgumentParser
+        :param namespace: The namespace object that will be returned by parse_args().
+        :type namespace: Any
+        :param values: The argument values associated with the action.
+        :type values: Any
+        :param option_string: The option string that was used to invoke this action.
+        :type option_string: Optional[str]
+        """
         getattr(namespace, self.dest).update(values)
 
 
-def get_rules(rules: str) -> set:
+def get_rules(rules: str) -> Set[str]:
+    """
+    Parse a string of rules and return a set of rule IDs.
+
+    :param rules: A string containing rule IDs separated by non-word characters.
+    :type rules: str
+    :return: A set of rule IDs.
+    :rtype: Set[str]
+    """
     return {rule.upper() for rule in re.findall(r"[\w\-]+", rules)}
 
 
-def get_text(filename, encoding, ignore):
+def get_text(filename: Union[str, int], encoding: Optional[str], ignore: Optional[str]) -> str:
+    """
+    Read the content of a file and return it as a string, optionally ignoring lines that match a regular expression.
+
+    :param filename: The name of the file to read or file descriptor.
+    :type filename: Union[str, int]
+    :param encoding: The encoding to use for reading the file.
+    :type encoding: Optional[str]
+    :param ignore: A regular expression pattern to match lines that should be ignored.
+    :type ignore: Optional[str]
+    :return: The content of the file as a string.
+    :rtype: str
+    """
     with open(filename, encoding=encoding) as f:
         text = ''.join('\n' if (ignore and re.match(ignore, line)) else line
                        for line in f.readlines())
     return text
 
 
-def main():
+def main() -> int:
+    """
+    Main function to parse arguments, process files, and check text using LanguageTool.
+
+    :return: Exit status code
+    :rtype: int
+    """
     args = parse_args()
 
     status = 0
@@ -106,7 +162,7 @@ def main():
         if args.remote_host is not None:
             remote_server = args.remote_host
             if args.remote_port is not None:
-                remote_server += ':{}'.format(args.remote_port)
+                remote_server += f':{args.remote_port}'
         lang_tool = LanguageTool(
             language=args.language,
             motherTongue=args.mother_tongue,
@@ -116,7 +172,7 @@ def main():
         try:
             text = get_text(filename, encoding, ignore=args.ignore_lines)
         except UnicodeError as exception:
-            print('{}: {}'.format(filename, exception), file=sys.stderr)
+            print(f'{filename}: {exception}', file=sys.stderr)
             continue
 
         if not args.spell_check:
@@ -137,7 +193,7 @@ def main():
                     rule_id = match.ruleId
 
                     replacement_text = ', '.join(
-                        "'{}'".format(word)
+                        f"'{word}'"
                         for word in match.replacements).strip()
 
                     message = match.message
@@ -147,14 +203,11 @@ def main():
                     if replacement_text and not message.endswith(('.', '?')):
                         message += '; suggestions: ' + replacement_text
 
-                    print('{}: {}: {}'.format(
-                        filename,
-                        rule_id,
-                        message))
+                    print(f'{filename}: {rule_id}: {message}')
 
                     status = 2
         except LanguageToolError as exception:
-            print('{}: {}'.format(filename, exception), file=sys.stderr)
+            print(f'{filename}: {exception}', file=sys.stderr)
             continue
 
     return status

language_tool_python/config_file.py

@@ -4,6 +4,7 @@
 import os
 import tempfile
 
+# Allowed configuration keys for LanguageTool.
 ALLOWED_CONFIG_KEYS = { 
     'maxTextLength', 'maxTextHardLength', 'maxCheckTimeMillis', 'maxErrorsPerWordRate',
     'maxSpellingSuggestions', 'maxCheckThreads', 'cacheSize', 'cacheTTLSeconds', 'requestLimit',
@@ -12,10 +13,25 @@
     'blockedReferrers', 'premiumOnly', 'disabledRuleIds', 'pipelineCaching', 'maxPipelinePoolSize',
     'pipelineExpireTimeInSeconds', 'pipelinePrewarming'
 }
+
 class LanguageToolConfig:
+    """
+    Configuration class for LanguageTool.
+
+    :param config: Dictionary containing configuration keys and values.
+    :type config: Dict[str, Any]
+
+    Attributes:
+        config (Dict[str, Any]): Dictionary containing configuration keys and values.
+        path (str): Path to the temporary file storing the configuration.
+    """
     config: Dict[str, Any]
     path: str
+
     def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize the LanguageToolConfig object.
+        """
         assert set(config.keys()) <= ALLOWED_CONFIG_KEYS, f"unexpected keys in config: {set(config.keys()) - ALLOWED_CONFIG_KEYS}"
         assert len(config), "config cannot be empty"
         self.config = config
@@ -31,9 +47,15 @@ def __init__(self, config: Dict[str, Any]):
         self.path = self._create_temp_file()
 
     def _create_temp_file(self) -> str:
+        """
+        Create a temporary file to store the configuration.
+
+        :return: Path to the temporary file.
+        :rtype: str
+        """
         tmp_file = tempfile.NamedTemporaryFile(delete=False)
 
-        # WRite key=value entries as lines in temporary file.
+        # Write key=value entries as lines in temporary file.
         for key, value in self.config.items():
             next_line = f'{key}={value}\n'
             tmp_file.write(next_line.encode())
@@ -43,63 +65,3 @@ def _create_temp_file(self) -> str:
         atexit.register(lambda: os.unlink(tmp_file.name))
 
         return tmp_file.name
-
-
-
-"""
-❯ /usr/bin/java -cp /Users/johnmorris/.cache/language_tool_python/LanguageTool-5.6/languagetool-server.jar org.languagetool.server.HTTPServer --help
-Usage: HTTPServer [--config propertyFile] [--port|-p port] [--public]
-  --config FILE  a Java property file (one key=value entry per line) with values for:
-                 'maxTextLength' - maximum text length, longer texts will cause an error (optional)
-                 'maxTextHardLength' - maximum text length, applies even to users with a special secret 'token' parameter (optional)
-                 'secretTokenKey' - secret JWT token key, if set by user and valid, maxTextLength can be increased by the user (optional)
-                 'maxCheckTimeMillis' - maximum time in milliseconds allowed per check (optional)
-                 'maxErrorsPerWordRate' - checking will stop with error if there are more rules matches per word (optional)
-                 'maxSpellingSuggestions' - only this many spelling errors will have suggestions for performance reasons (optional,
-                                            affects Hunspell-based languages only)
-                 'maxCheckThreads' - maximum number of threads working in parallel (optional)
-                 'cacheSize' - size of internal cache in number of sentences (optional, default: 0)
-                 'cacheTTLSeconds' - how many seconds sentences are kept in cache (optional, default: 300 if 'cacheSize' is set)
-                 'requestLimit' - maximum number of requests per requestLimitPeriodInSeconds (optional)
-                 'requestLimitInBytes' - maximum aggregated size of requests per requestLimitPeriodInSeconds (optional)
-                 'timeoutRequestLimit' - maximum number of timeout request (optional)
-                 'requestLimitPeriodInSeconds' - time period to which requestLimit and timeoutRequestLimit applies (optional)
-                 'languageModel' - a directory with '1grams', '2grams', '3grams' sub directories which contain a Lucene index
-                                   each with ngram occurrence counts; activates the confusion rule if supported (optional)
-                 'word2vecModel' - a directory with word2vec data (optional), see
-                  https://github.com/languagetool-org/languagetool/blob/master/languagetool-standalone/CHANGES.md#word2vec
-                 'fasttextModel' - a model file for better language detection (optional), see
-                                   https://fasttext.cc/docs/en/language-identification.html
-                 'fasttextBinary' - compiled fasttext executable for language detection (optional), see
-                                    https://fasttext.cc/docs/en/support.html
-                 'maxWorkQueueSize' - reject request if request queue gets larger than this (optional)
-                 'rulesFile' - a file containing rules configuration, such as .langugagetool.cfg (optional)
-                 'warmUp' - set to 'true' to warm up server at start, i.e. run a short check with all languages (optional)
-                 'blockedReferrers' - a comma-separated list of HTTP referrers (and 'Origin' headers) that are blocked and will not be served (optional)
-                 'premiumOnly' - activate only the premium rules (optional)
-                 'disabledRuleIds' - a comma-separated list of rule ids that are turned off for this server (optional)
-                 'pipelineCaching' - set to 'true' to enable caching of internal pipelines to improve performance
-                 '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)
-                 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)
-  --port, -p PRT   port to bind to, defaults to 8081 if not specified
-  --public         allow this server process to be connected from anywhere; if not set,
-                   it can only be connected from the computer it was started on
-  --allow-origin [ORIGIN] set the Access-Control-Allow-Origin header in the HTTP response,
-                         used for direct (non-proxy) JavaScript-based access from browsers.
-                         Example: --allow-origin "https://my-website.org"
-                         Don't set a parameter for `*`, i.e. access from all websites.
-  --verbose, -v    in case of exceptions, log the input text (up to 500 characters)
-  --languageModel  a directory with '1grams', '2grams', '3grams' sub directories (per language)
-                         which contain a Lucene index (optional, overwrites 'languageModel'
-                         parameter in properties files)
-  --word2vecModel  a directory with word2vec data (optional), see
-                   https://github.com/languagetool-org/languagetool/blob/master/languagetool-standalone/CHANGES.md#word2vec
-  --premiumAlways  activate the premium rules even when user has no username/password - useful for API servers
-"""