fix deletion handlers, add unit tests for closing LTP, add examples of with..as and close() to the README, remove backports references

Author: jxmorris12

README.md

@@ -65,6 +65,8 @@ From the interpreter:
 >>> matches = tool.check(text)
 >>> len(matches)
 2
+...
+>>> tool.close() # Call `close()` to shut off the server when you're done.
 ```
 
 Check out some ``Match`` object attributes:
@@ -101,6 +103,28 @@ $ language_tool_python example.txt
 example.txt:1:1: THIS_NNS[3]: Did you mean 'these'?
 ```
 
+## Closing LanguageTool
+
+`language_tool_python` runs a LanguageTool Java server in the background. It will shut the server off when garbage collected, for example when a created `language_tool_python.LanguageTool` object goes out of scope. However, if garbage collection takes awhile, the process might not get deleted right away. If you're seeing lots of processes get spawned and not get deleted, you can explicitly close them:
+
+
+```python
+import language_tool_python
+tool = language_tool_python.LanguageToolPublicAPI('de-DE') # starts a process
+# do stuff with `tool`
+tool.close() # explicitly shut off the LanguageTool
+```
+
+You can also use a context manager (`with .. as`) to explicitly control when the server is started and stopped:
+
+```python
+import language_tool_python
+
+with language_tool_python.LanguageToolPublicAPI('de-DE') as tool:
+  # do stuff with `tool`
+# no need to call `close() as it will happen at the end of the with statement
+```
+
 ## Installation
 
 To install via pip:

language_tool_python/backports/__init__.py

@@ -28,7 +28,7 @@
 BASE_URL = os.environ.get('LTP_DOWNLOAD_HOST', 'https://www.languagetool.org/download/')
 FILENAME = 'LanguageTool-{version}.zip'
 
-LATEST_VERSION = '5.5'
+LATEST_VERSION = '5.6'
 
 JAVA_VERSION_REGEX = re.compile(
     r'^(?:java|openjdk) version "(?P<major1>\d+)(|\.(?P<major2>\d+)\.[^"]+)"',
@@ -104,7 +104,7 @@ def http_get(url, out_file, proxies=None):
     total = int(content_length) if content_length is not None else None
     if req.status_code == 403: # Not found on AWS
         raise Exception('Could not find at URL {}.'.format(url))
-    progress = tqdm.tqdm(unit="B", unit_scale=True, total=total, desc='Downloading LanguageTool')
+    progress = tqdm.tqdm(unit="B", unit_scale=True, total=total, desc=f'Downloading LanguageTool {LATEST_VERSION}')
     for chunk in req.iter_content(chunk_size=1024):
         if chunk: # filter out keep-alive new chunks
             progress.update(len(chunk))

language_tool_python/backports/subprocess.py

@@ -1,4 +1,4 @@
-from typing import Dict
+from typing import Dict, List
 
 import atexit
 import http.client
@@ -7,11 +7,10 @@
 import re
 import requests
 import socket
+import subprocess
 import threading
 import urllib.parse
-from weakref import WeakValueDictionary
 
-from .backports import subprocess
 from .download_lt import download_lt
 from .language_tag import LanguageTag
 from .match import Match
@@ -26,21 +25,20 @@
 
 # Keep track of running server PIDs in a global list. This way,
 # we can ensure they're killed on exit.
-RUNNING_SERVER_PROCESSES = []
+RUNNING_SERVER_PROCESSES: List[subprocess.Popen] = []
 
 class LanguageTool:
-    """ Main class used for checking text against different rules. 
-        LanguageTool v2 API documentation: https://languagetool.org/http-api/swagger-ui/#!/default/post_check
+    """Main class used for checking text against different rules. 
+    LanguageTool v2 API documentation: https://languagetool.org/http-api/swagger-ui/#!/default/post_check
     """
     _HOST = socket.gethostbyname('localhost')
     _MIN_PORT = 8081
     _MAX_PORT = 8999
     _TIMEOUT = 5 * 60
     _remote = False
     _port = _MIN_PORT
-    _server = None
-    _consumer_thread = None
-    _instances = WeakValueDictionary()
+    _server: subprocess.Popen = None
+    _consumer_thread: threading.Thread = None
     _PORT_RE = re.compile(r"(?:https?://.*:|port\s+)(\d+)", re.I)
 
     def __init__(self, language=None, motherTongue=None, remote_server=None, newSpellings=None, new_spellings_persist=True):
@@ -68,20 +66,22 @@ def __init__(self, language=None, motherTongue=None, remote_server=None, newSpel
         self.disabled_categories = set()
         self.enabled_categories = set()
         self.enabled_rules_only = False
-        self._instances[id(self)] = self
-
+    
     def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
+    def __del__(self):
+        self.close()
+
     def __repr__(self):
         return '{}(language={!r}, motherTongue={!r})'.format(
             self.__class__.__name__, self.language, self.motherTongue)
 
     def close(self):
-        if not self._instances and self._server_is_alive():
+        if self._server_is_alive():
             self._terminate_server()
         if not self._new_spellings_persist and self._new_spellings:
             self._unregister_spellings()
@@ -311,7 +311,7 @@ def _terminate_server(self):
         return LanguageToolError_message
 
 class LanguageToolPublicAPI(LanguageTool):
-    """  Language tool client of the official API. """
+    """Language tool client of the official API."""
     def __init__(self, *args, **kwargs):
         super().__init__(*args, remote_server='https://languagetool.org/api/', **kwargs)
 

language_tool_python/download_lt.py

@@ -3,11 +3,11 @@
 import locale
 import os
 import re
+import subprocess
 import sys
 import urllib.parse
 import urllib.request
 
-from .backports import subprocess
 from .match import Match
 from .which import which
 

language_tool_python/server.py

@@ -7,7 +7,7 @@
 
 setup(
     name='language_tool_python',
-    version='2.6.2',
+    version='2.6.3',
     description='Checks grammar using LanguageTool.',
     long_description_content_type='text/markdown',
     long_description=long_description,

language_tool_python/utils.py

@@ -5,6 +5,34 @@ def test_langtool_load():
 	matches = lang_tool.check('ain\'t nothin but a thang')
 	assert str(matches) == """[Match({'ruleId': 'UPPERCASE_SENTENCE_START', 'message': 'This sentence does not start with an uppercase letter.', 'replacements': ['Ai'], 'offsetInContext': 0, 'context': "ain't nothin but a thang", 'offset': 0, 'errorLength': 2, 'category': 'CASING', 'ruleIssueType': 'typographical', 'sentence': "ain't nothin but a thang"}), Match({'ruleId': 'MORFOLOGIK_RULE_EN_US', 'message': 'Possible spelling mistake found.', 'replacements': ['nothing', 'no thin'], 'offsetInContext': 6, 'context': "ain't nothin but a thang", 'offset': 6, 'errorLength': 6, 'category': 'TYPOS', 'ruleIssueType': 'misspelling', 'sentence': "ain't nothin but a thang"}), Match({'ruleId': 'MORFOLOGIK_RULE_EN_US', 'message': 'Possible spelling mistake found.', 'replacements': ['than', 'thing', 'hang', 'thank', 'Chang', 'tang', 'thong', 'twang', 'Thant', 'thane', 'Thanh', 'Jhang', 'Shang', 'Zhang'], 'offsetInContext': 19, 'context': "ain't nothin but a thang", 'offset': 19, 'errorLength': 5, 'category': 'TYPOS', 'ruleIssueType': 'misspelling', 'sentence': "ain't nothin but a thang"})]"""
 
+
+def test_process_starts_and_stops():
+	import language_tool_python
+	with language_tool_python.LanguageTool("en-US") as lang_tool:
+		proc: subprocess.Popen = lang_tool._server
+		# Make sure process is running before killing language tool object.
+		assert proc.poll() is None, "lang_tool._server not running after creation"
+		# lang_tool.close() # Explicitly close() object so process stops before garbage collection.
+	# Make sure process stopped after close() was called.
+	assert proc.poll() is not None, "lang_tool._server should stop running after deletion"
+	import time; time.sleep(10)
+	# if poll is None: # p.subprocess is alive
+
+def test_process_starts_and_closes():
+	import language_tool_python
+	lang_tool = language_tool_python.LanguageTool("en-US")
+	proc: subprocess.Popen = lang_tool._server
+	# Make sure process is running before killing language tool object.
+	assert proc.poll() is None, "lang_tool._server not running after creation"
+	lang_tool.close() # Explicitly close() object so process stops before garbage collection.
+	del lang_tool
+	# Make sure process stopped after close() was called.
+	assert proc.poll() is not None, "lang_tool._server should stop running after deletion"
+	# if poll is None: # p.subprocess is alive
+	
+
+# TODO(jxm): Add test to confirm that multiple instances connect to the same process instead of starting new ones.
+
 def test_langtool_languages():
 	import language_tool_python
 	lang_tool = language_tool_python.LanguageTool("en-US")