advanced.rst

Advanced usage

This page covers advanced usage patterns that go beyond the basic check/correct workflow.

Pinning the LanguageTool version

By default, language_tool_python downloads LanguageTool :data:`~language_tool_python.download_lt.LTP_DOWNLOAD_VERSION`. Use the language_tool_download_version parameter to force a specific version, useful for reproducible results or testing against a particular release:

import language_tool_python

with language_tool_python.LanguageTool(
    "en-US",
    language_tool_download_version="6.7",
) as tool:
    matches = tool.check("A sentence with a error in the Hitchhiker's Guide tot he Galaxy")

print(matches[0].message)
# → Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.

Accepted formats:

• "X.Y" - a release version (e.g. "6.7", "4.0"). Versions below 4.0 are not supported.
• "YYYYMMDD" - a snapshot identified by date (e.g. "20260201").
• "latest" - the most recent snapshot.

Authenticating with a premium API key

If you have a LanguageTool premium account, assign your username and API key to :attr:`~language_tool_python.server.LanguageTool.premium_username` and :attr:`~language_tool_python.server.LanguageTool.premium_key` before calling :meth:`~language_tool_python.server.LanguageTool.check`. They are forwarded to the public API as the username and apiKey parameters respectively:

import os
import language_tool_python

with language_tool_python.LanguageToolPublicAPI("en-US") as tool:
    tool.premium_username = os.environ["LANGUAGETOOL_USERNAME"]
    tool.premium_key = os.environ["LANGUAGETOOL_API_KEY"]
    print(tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy"))
    # → A sentence with an error in the Hitchhiker's Guide to the Galaxy

Client/server pattern

You can start the LanguageTool Java process once and connect to it from multiple client instances, avoiding the per-check startup overhead:

import language_tool_python

# Start the server once, this launches the Java process
server_tool = language_tool_python.LanguageTool("en-US")

# Connect as a lightweight client using the server's port
client_tool = language_tool_python.LanguageTool(
    "en-US",
    remote_server=f"http://127.0.0.1:{server_tool.port}",
)

print(client_tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy"))
# → A sentence with an error in the Hitchhiker's Guide to the Galaxy
server_tool.close()

This pattern is also useful to share a single server across multiple threads or processes.

Resource management

When using a local server, the LanguageTool Java process must be terminated explicitly. The recommended approach is a context manager, which calls :meth:`~language_tool_python.server.LanguageTool.close` automatically on exit:

import language_tool_python

with language_tool_python.LanguageTool("en-US") as tool:
    print(tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy"))
    # → A sentence with an error in the Hitchhiker's Guide to the Galaxy
# Java process is terminated here

For longer-lived instances, call :meth:`~language_tool_python.server.LanguageTool.close` explicitly:

import language_tool_python

tool = language_tool_python.LanguageTool("en-US")
try:
    print(tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy"))
    # → A sentence with an error in the Hitchhiker's Guide to the Galaxy
finally:
    tool.close()

Warning

Forgetting to call close() (or not using a context manager) leaves the Java process running until the Python interpreter exits.

Error handling

All library exceptions inherit from :class:`~language_tool_python.exceptions.LanguageToolError`, so a single except clause is enough to catch any library error:

import language_tool_python
from language_tool_python.exceptions import LanguageToolError

try:
    with language_tool_python.LanguageTool("en-US") as tool:
        print(tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy"))
        # → A sentence with an error in the Hitchhiker's Guide to the Galaxy
except LanguageToolError as exc:
    print(f"LanguageTool error: {exc}")

More specific exception classes (all in :mod:`language_tool_python.exceptions`):

• :class:`~language_tool_python.exceptions.ServerError` - the Java server failed to start or crashed.
• :class:`~language_tool_python.exceptions.JavaError` - Java is not installed or the version is incompatible.
• :class:`~language_tool_python.exceptions.PathError` - a path-like config value does not point to an existing file.
• :class:`~language_tool_python.exceptions.RateLimitError` - the public API rate limit was exceeded.