language_tool_python package¶

Submodules¶

language_tool_python.config_file module¶

Module for configuring LanguageTool’s local server.

class language_tool_python.config_file.LanguageToolConfig(config: Dict[str, Any])¶

Bases: object

Configuration class for LanguageTool.

Parameters:: config (Dict[str, Any]) – Dictionary containing configuration keys and values.

config: Dict[str, Any]¶: Dictionary containing configuration keys and values.

path: str¶: Path to the temporary file storing the configuration.

class language_tool_python.config_file.OptionSpec(py_types: type | Tuple[type, ...], encoder: Callable[[Any], str], validator: Callable[[Any], None] | None = None)¶

Bases: object

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.

This class is frozen (immutable) to ensure configuration specifications remain constant throughout the application lifecycle.

encoder: Callable[[Any], str]¶: A callable that converts the option value to its string representation.

py_types: type | Tuple[type, ...]¶: The Python type(s) that this option accepts.

validator: Callable[[Any], None] | None = None¶: An optional validator function for the option value.

language_tool_python.download_lt module¶

LanguageTool download module.

class language_tool_python.download_lt.LocalLanguageTool¶

Bases: ABC

Abstract base class for managing local LanguageTool installations.

This class provides common functionality for handling LanguageTool downloads, installations, and server command generation. It supports both release versions and snapshot versions through its subclasses.

abstractmethod download() → None¶

Download and install the LanguageTool version.

This abstract method must be implemented by subclasses to handle version-specific download logic.

abstract property download_url: str¶

Get the download URL for this LanguageTool version.

This abstract property must be implemented by subclasses to return the appropriate download URL.

Returns:: The download URL.
Return type:: str

classmethod from_path(path: Path) → LocalLanguageTool¶

Create a LocalLanguageTool instance from a directory path.

This factory method extracts the version name from a LanguageTool directory path and creates the appropriate instance.

Parameters:: path (Path) – The path to a LanguageTool installation directory.
Returns:: An instance of the appropriate LocalLanguageTool subclass.
Return type:: LocalLanguageTool
Raises:: ValueError – If the version cannot be determined from the path.

classmethod from_version_name(version_name: str = 'latest') → LocalLanguageTool¶

Create a LocalLanguageTool instance from a version name.

This factory method determines the appropriate subclass (ReleaseLocalLanguageTool or SnapshotLocalLanguageTool) based on the version name format.

Parameters:: version_name (str) – The version name (e.g., ‘6.0’, ‘20240101’, or ‘latest’).
Returns:: An instance of the appropriate LocalLanguageTool subclass.
Return type:: LocalLanguageTool
Raises:: ValueError – If the version name format is not recognized.

get_directory_path() → Path¶

Get the installation directory path for this LanguageTool version.

This method searches the download folder for the directory matching this version’s name.

Returns:: The path to the LanguageTool installation directory.
Return type:: Path
Raises:: FileNotFoundError – If the LanguageTool version directory is not found.

classmethod get_installed_versions() → List[LocalLanguageTool]¶

Get a list of all installed LanguageTool versions.

This method scans the download directory for LanguageTool installations and returns a list of LocalLanguageTool instances representing each version.

Returns:: A list of installed LocalLanguageTool instances.
Return type:: List[LocalLanguageTool]

get_jar_path() → Path¶

Get the path to the LanguageTool JAR file.

This method locates the main JAR file (languagetool-server.jar or languagetool.jar) within the installation directory.

Returns:: The path to the LanguageTool JAR file.
Return type:: Path
Raises:: FileNotFoundError – If no LanguageTool JAR file is found.

classmethod get_latest_installed_version() → LocalLanguageTool | None¶

Get the latest installed LanguageTool version.

This method finds all installed versions and returns the most recent one according to version ordering.

Returns:: The latest installed LocalLanguageTool instance, or None if no versions are installed.
Return type:: Optional[LocalLanguageTool]

get_server_cmd(port: int | None = None, config: LanguageToolConfig | None = None) → List[str]¶

Generate the command to start the LanguageTool HTTP server.

Parameters:

port (Optional[int]) – Optional; The port number on which the server should run. If not provided, the default port will be used.
config (Optional[LanguageToolConfig]) – Optional; The configuration for the LanguageTool server. If not provided, default configuration will be used.

Returns:

A list of command line arguments to start the LanguageTool HTTP server.

Return type:

List[str]

abstract property version_into: Version | datetime¶

Get the version as a comparable object.

This abstract property must be implemented by subclasses to return the version as either a Version object (for releases) or datetime object (for snapshots) for comparison purposes.

Returns:: A Version object for releases or datetime for snapshots.
Return type:: Union[Version, datetime]

abstract property version_name: str¶

Get the version name string.

This abstract property must be implemented by subclasses to return the version identifier.

Returns:: The version name.
Return type:: str

class language_tool_python.download_lt.ReleaseLocalLanguageTool(version: str)¶

Bases: LocalLanguageTool

Represents a release version of LanguageTool.

This class handles release versions of LanguageTool (e.g., ‘6.0’, ‘5.9’) which are downloaded from the official release pages.

Releases are the old way of downloading LanguageTool.

Parameters:: version (str) – The release version string (e.g., ‘6.0’).

download() → None¶

Download and install this release version of LanguageTool.

This method checks Java compatibility, downloads the release ZIP file, and extracts it to the download folder if not already installed.

property download_url: str¶

Get the download URL for this release version.

URLs are constructed based on version: - Versions >= 6.0 are downloaded from the main release page - Versions 4.0 - 5.9 are downloaded from the archive - Versions < 4.0 are not supported

Returns:: The download URL for this version.
Return type:: str
Raises:: PathError – If the version is below 4.0 (unsupported).

property version_into: Version¶

Get the version as a Version object for comparison.

Returns:: A parsed Version object from the version string.
Return type:: Version

property version_name: str¶

Get the release version name.

Returns:: The release version string.
Return type:: str

class language_tool_python.download_lt.SnapshotLocalLanguageTool(version_name: str)¶

Bases: LocalLanguageTool

Represents a snapshot (development) version of LanguageTool.

This class handles snapshot versions of LanguageTool, which are nightly builds identified by date strings (e.g., ‘20240101’) or ‘latest’.

Snapshots are the new common way of downloading LanguageTool.

Parameters:: version_name (str) – The snapshot version (date string or ‘latest’).

download() → None¶

Download and install this snapshot version of LanguageTool.

This method checks Java compatibility, downloads the snapshot ZIP file, and extracts it to the download folder. For snapshots, the extracted directory is renamed to match the expected version name if necessary.

property download_url: str¶

Get the download URL for this snapshot version.

Constructs the URL to download the snapshot from the snapshot server.

Returns:: The download URL for this snapshot.
Return type:: str

property version_into: datetime¶

Get the snapshot version as a datetime object for comparison.

Converts the version date string to a datetime object. For ‘latest’, uses the current date.

Returns:: A datetime object representing the snapshot date.
Return type:: datetime

property version_name: str¶

Get the snapshot version name.

Returns the current snapshot version string if ‘latest’ was specified, otherwise returns the specified date string.

Returns:: The snapshot version string.
Return type:: str

language_tool_python.download_lt.confirm_java_compatibility(language_tool_version: str = 'latest') → None¶

Confirms if the installed Java version is compatible with language-tool-python. This function checks if Java is installed and verifies that the major version is at least 9 or 17 (depending on the LanguageTool version). It raises an error if Java is not installed or if the version is incompatible.

Parameters:

language_tool_version (str) – The version of LanguageTool to check compatibility for.

Raises:

ModuleNotFoundError – If no Java installation is detected.
SystemError – If the detected Java version is less than the required version.

language_tool_python.download_lt.download_lt(language_tool_version: str = 'latest') → None¶

Downloads and extracts the specified version of LanguageTool. This function checks for Java compatibility, and downloads the specified version of LanguageTool if it is not already present.

Parameters:

language_tool_version (str) – The version of LanguageTool to download. If not specified, the default version defined by LTP_DOWNLOAD_VERSION is used.

Raises:

PathError – If the download folder is not a directory.
ValueError – If the specified version format is invalid.

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.download_lt.download_zip(url: str, directory: Path) → None¶

Downloads a ZIP file from the given URL and extracts it to the specified directory.

Parameters:

url (str) – The URL of the ZIP file to download.
directory (Path) – The directory where the ZIP file should be extracted.

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.download_lt.get_common_prefix(z: ZipFile) → str | None¶

Determine the common prefix of all file names in a zip archive.

Parameters:: z (zipfile.ZipFile) – A ZipFile object representing the zip archive.
Returns:: The common prefix of all file names in the zip archive, or None if there is no common prefix.
Return type:: Optional[str]

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.download_lt.http_get(url: str, out_file: IO[bytes], proxies: Dict[str, str] | None = None) → None¶: Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.download_lt.parse_java_version(version_text: str) → Tuple[int, int]¶

Parse the Java version from a given version text.

This function attempts to extract the major version numbers from the provided Java version string using regular expressions. It supports two different version formats defined by JAVA_VERSION_REGEX and JAVA_VERSION_REGEX_UPDATED.

Parameters:: version_text (str) – The Java version string to parse.
Returns:: A tuple containing the major version numbers.
Return type:: Tuple[int, int]
Raises:: SystemExit – If the version string cannot be parsed.

language_tool_python.download_lt.unzip_file(temp_file_name: str, directory_to_extract_to: Path) → None¶

Unzips a zip file to a specified directory.

Parameters:

temp_file_name (str) – A temporary file object representing the zip file to be extracted.
directory_to_extract_to (Path) – The directory where the contents of the zip file will be extracted.

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.exceptions module¶

exception language_tool_python.exceptions.JavaError¶

Bases: 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.

exception language_tool_python.exceptions.LanguageToolError¶

Bases: 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.

exception language_tool_python.exceptions.PathError¶

Bases: 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.

exception language_tool_python.exceptions.RateLimitError¶

Bases: 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.

exception language_tool_python.exceptions.ServerError¶

Bases: 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.

language_tool_python.language_tag module¶

LanguageTool language tag normalization module.

class language_tool_python.language_tag.LanguageTag(tag: str, languages: Iterable[str])¶

Bases: object

A class to represent and normalize language tags.

Parameters:

tag (str) – The language tag.
languages (Iterable[str]) – An iterable of supported language tags.

languages: Iterable[str]¶: An iterable of supported language tags.

normalized_tag: str¶: The normalized language tag.

tag: str¶: The language tag to be normalized.

language_tool_python.match module¶

LanguageTool API Match object representation and utility module.

class language_tool_python.match.Match(attrib: Dict[str, Any], text: str)¶

Bases: object

Represents a match object that contains information about a language rule violation.

Parameters:

attrib (Dict[str, Any]) –
A dictionary containing various attributes for the match. The dictionary is expected to have the following keys:
- rule (Dict[str, Any]): A dictionary with keys category (which has an id) and id, issueType.
- context (Dict[str, Any]): A dictionary with keys offset and text.
- replacements (List[Dict[str, str]]): A list of dictionaries, each containing a value.
- length (int): The length of the error.
- message (str): The message describing the error.
text (str) – The original text in which the error occurred (the whole text, not just the context).

Example of a match object received from the LanguageTool API :

{
    'message': 'Possible spelling mistake found.',
    'shortMessage': 'Spelling mistake',
    'replacements': [{'value': 'newt'}, {'value': 'not'}, {'value': 'new', 'shortDescription': 'having just been made'}, {'value': 'news'}, {'value': 'foot', 'shortDescription': 'singular'}, {'value': 'root', 'shortDescription': 'underground organ of a plant'}, {'value': 'boot'}, {'value': 'noon'}, {'value': 'loot', 'shortDescription': 'plunder'}, {'value': 'moot'}, {'value': 'Root'}, {'value': 'soot', 'shortDescription': 'carbon black'}, {'value': 'newts'}, {'value': 'nook'}, {'value': 'Lieut'}, {'value': 'coot'}, {'value': 'hoot'}, {'value': 'toot'}, {'value': 'snoot'}, {'value': 'neut'}, {'value': 'nowt'}, {'value': 'Noor'}, {'value': 'noob'}],
    'offset': 8,
    'length': 4,
    'context': {'text': 'This is noot okay. ', 'offset': 8, 'length': 4}, 'sentence': 'This is noot okay.',
    'type': {'typeName': 'Other'},
    'rule': {'id': 'MORFOLOGIK_RULE_EN_US', 'description': 'Possible spelling mistake', 'issueType': 'misspelling', 'category': {'id': 'TYPOS', 'name': 'Possible Typo'}},
    'ignoreForIncompleteSentence': False,
    'contextForSureMatch': 0
}

FOUR_BYTES_POSITIONS: List[int] | None = None¶: The positions of 4-byte encoded characters in the text, registered by the previous match object (kept for optimization purposes if the text is the same).

PREVIOUS_MATCHES_TEXT: str | None = None¶: The text of the previous match object.

category: str¶: The category of the rule that was violated.

context: str¶: The context in which the error occurred.

error_length: int¶: The length of the error.

get_line_and_column(original_text: str) → Tuple[int, int]¶

Returns the line and column number of the error in the context.

Parameters:: original_text (str) – The original text in which the error occurred. We need this to calculate the line and column number, because the context has no more newline characters.
Returns:: A tuple containing the line and column number of the error.
Return type:: Tuple[int, int]

property matched_text: str¶

Returns the substring from the context that corresponds to the matched text.

Returns:: The matched text from the context.
Return type:: str

message: str¶: The message describing the error.

offset: int¶: The offset of the error.

offset_in_context: int¶: The offset of the error in the context.

replacements: List[str]¶: A list of suggested replacements for the error.

rule_id: str¶: The ID of the rule that was violated.

rule_issue_type: str¶: The issue type of the rule that was violated.

select_replacement(index: int) → None¶

Select a single replacement suggestion based on the given index and update the replacements list, leaving only the selected replacement.

Parameters:

index (int) – The index of the replacement to select.

Raises:

ValueError – If there are no replacement suggestions.
ValueError – If the index is out of the valid range.

language_tool_python.match.auto_type(obj: Any) → Any¶

Attempts to automatically convert the input object to an integer or float. If the conversion to an integer fails, it tries to convert to a float. If both conversions fail, it returns the original object.

Parameters:: obj (Any) – The object to be converted.
Returns:: The converted object as an integer, float, or the original object.
Return type:: Any

language_tool_python.match.four_byte_char_positions(text: str) → List[int]¶

Identify positions of 4-byte encoded characters in a UTF-8 string. This function scans through the input text and identifies the positions of characters that are encoded with 4 bytes in UTF-8. These characters are typically non-BMP (Basic Multilingual Plane) characters, such as certain emoji and some rare Chinese, Japanese, and Korean characters.

Parameters:: text (str) – The input string to be analyzed.
Returns:: A list of positions where 4-byte encoded characters are found.
Return type:: List[int]

language_tool_python.match.get_match_ordered_dict() → OrderedDict[str, type]¶

Returns an ordered dictionary with predefined keys and their corresponding types.

Returns:: An OrderedDict where each key is a string representing a specific attribute and each value is the type of that attribute.
Return type:: OrderedDictType[str, type]

The keys and their corresponding types are:

‘rule_id’: str
‘message’: str
‘replacements’: list
‘offset_in_context’: int
‘context’: str
‘offset’: int
‘error_length’: int
‘category’: str
‘rule_issue_type’: str
‘sentence’: str

language_tool_python.server module¶

LanguageTool server management module.

class language_tool_python.server.LanguageTool(language: str | None = None, mother_tongue: str | None = None, remote_server: str | None = None, new_spellings: List[str] | None = None, new_spellings_persist: bool = True, host: str | None = None, config: Dict[str, Any] | None = None, language_tool_download_version: str = 'latest', proxies: Dict[str, str] | None = None)¶

Bases: object

A class to interact with the LanguageTool server for text checking and correction.

Parameters:

language (Optional[str]) – The language to be used by the LanguageTool server. If None, it will try to detect the system language.
mother_tongue (Optional[str]) – The mother tongue of the user.
remote_server (Optional[str]) – URL of a remote LanguageTool server. If provided, the local server will not be started.
new_spellings (Optional[List[str]]) – Custom spellings to be added to the LanguageTool server.
new_spellings_persist (Optional[bool]) – Whether the new spellings should persist across sessions.
host (Optional[str]) – The host address for the LanguageTool server. Defaults to ‘localhost’.
config (Optional[str]) – Path to a configuration file for the LanguageTool server.
language_tool_download_version (Optional[str]) – The version of LanguageTool to download if needed.
proxies (Optional[Dict[str, str]]) – A dictionary of proxies to use for server requests (e.g., {‘http’: ‘http://proxy:port’, ‘https’: ‘https://proxy:port’}).

check(text: str) → List[Match]¶

Checks the given text for language issues using the LanguageTool server.

Parameters:: text (str) – The text to be checked for language issues.
Returns:: A list of Match objects representing the issues found in the text.
Return type:: List[Match]

check_matching_regions(text: str, pattern: str, flags: int = 0) → List[Match]¶

Check only the parts of the text that match a regex pattern. The returned Match objects can be applied to the original text with language_tool_python.utils.correct().

Parameters:

text – The full text.
pattern – Regular expression defining the regions to check
flags – Regex flags (re.IGNORECASE, re.MULTILINE, etc.)

Returns:

List of Match with offsets adjusted to the original text

Return type:

List[Match]

close() → None¶

Closes the server and performs necessary cleanup operations.

This method performs the following actions: 1. Checks if the server is alive, not remote and terminates it if necessary. 2. If new spellings are not set to persist and there are new spellings, it unregisters the spellings and clears the list of new spellings.

property config: LanguageToolConfig | None¶

Get the server configuration.

This property is read-only as the configuration is set during initialization and cannot be changed while the server is running.

Returns:: The configuration object if set, otherwise None.
Return type:: Optional[LanguageToolConfig]

correct(text: str) → str¶

Corrects the given text by applying language tool suggestions. Applies only the first suggestion for each issue.

Parameters:: text (str) – The text to be corrected.
Returns:: The corrected text.
Return type:: str

disable_spellchecking() → None¶: Disable spellchecking by updating the disabled categories with spell checking categories.

property disabled_categories: Set[str]¶

Get the set of disabled rule categories.

Returns:: A set of disabled category names.
Return type:: Set[str]

property disabled_rules: Set[str]¶

Get the set of disabled rules.

Returns:: A set of disabled rule IDs.
Return type:: Set[str]

enable_spellchecking() → None¶: Enable spellchecking by removing spell checking categories from the disabled categories set. This method updates the disabled_categories attribute by removing any categories that are related to spell checking, which are defined in the _SPELL_CHECKING_CATEGORIES class constant.

property enabled_categories: Set[str]¶

Get the set of enabled rule categories.

Returns:: A set of enabled category names.
Return type:: Set[str]

property enabled_rules: Set[str]¶

Get the set of enabled rules.

Returns:: A set of enabled rule IDs.
Return type:: Set[str]

property enabled_rules_only: bool¶

Get whether only enabled rules should be used.

Returns:: True if using only enabled rules, False otherwise.
Return type:: bool

property host: str¶

Get the local server host address.

This property is read-only as the host address is determined during initialization and cannot be changed while the server is running.

Returns:: The host address (e.g., ‘127.0.0.1’).
Return type:: str

property is_remote: bool¶

Get whether using a remote LanguageTool server.

This property is read-only as the remote status is determined during initialization and cannot be changed while the server is running.

Returns:: True if using a remote server, False if using a local server.
Return type:: bool

property language: LanguageTag¶

Get the language tag associated with the server.

Returns:: The language tag.
Return type:: LanguageTag

property language_tool_download_version: str¶

Get the LanguageTool version to download.

This property is read-only as the version is determined during initialization and the server cannot be re-downloaded with a different version at runtime.

Returns:: The LanguageTool version string.
Return type:: str

property mother_tongue: LanguageTag | None¶

Get the mother tongue language tag.

Returns:: The mother tongue language tag if set, otherwise None.
Return type:: Optional[LanguageTag]

property picky: bool¶

Get whether picky mode is enabled.

Returns:: True if picky mode is enabled, False otherwise.
Return type:: bool

property port: int¶

Get the local server port number.

This property is read-only as the port number is determined during initialization and cannot be changed while the server is running.

Returns:: The port number (e.g., 8081).
Return type:: int

property preferred_variants: Set[str]¶

Get the set of preferred language variants.

Returns:: A set of preferred variant codes.
Return type:: Set[str]

property proxies: Dict[str, str] | None¶

Get the proxies used for server requests.

Returns:: A dictionary of proxies if set, otherwise None.
Return type:: Optional[Dict[str, str]]

property url: str¶

Get the LanguageTool server URL.

This property is read-only as the URL is determined during initialization and cannot be changed while the server is running.

Returns:: The server URL (e.g., ‘http://localhost:8081/v2/’).
Return type:: str

class language_tool_python.server.LanguageToolPublicAPI(*args: Any, **kwargs: Any)¶

Bases: LanguageTool

A class to interact with the public LanguageTool API. This class extends the LanguageTool class and initializes it with the remote server set to the public LanguageTool API endpoint.

Parameters:

args (Any) – Positional arguments passed to the parent class initializer.
kwargs (Any) – Keyword arguments passed to the parent class initializer.

language_tool_python.server.terminate_server() → None¶: Terminates all running server processes. This function iterates over the list of running server processes and forcefully kills each process by its PID.

language_tool_python.utils module¶

Utility functions for the LanguageTool library.

class language_tool_python.utils.TextStatus(*values)¶

Bases: Enum

CORRECT = 'correct'¶

FAULTY = 'faulty'¶

GARBAGE = 'garbage'¶

language_tool_python.utils.classify_matches(matches: List[Match]) → TextStatus¶

Classify the matches (result of a check on a text) into one of three categories: CORRECT, FAULTY, or GARBAGE. This function checks the status of the matches and returns a corresponding TextStatus value.

Parameters:: matches (List[Match]) – A list of Match objects to be classified.
Returns:: The classification of the matches as a TextStatus value.
Return type:: TextStatus

language_tool_python.utils.correct(text: str, matches: List[Match]) → str¶

Corrects the given text based on the provided matches. Only the first replacement for each match is applied to the text.

Parameters:

text (str) – The original text to be corrected.
matches (List[Match]) – A list of Match objects that contain the positions and replacements for errors in the text.

Returns:

The corrected text.

Return type:

str

language_tool_python.utils.find_existing_language_tool_downloads(download_folder: Path) → List[Path]¶

Find existing LanguageTool downloads in the specified folder. This function searches for directories in the given download folder that match the pattern ‘LanguageTool*’ and returns a list of their paths.

Parameters:: download_folder (Path) – The folder where LanguageTool downloads are stored.
Returns:: A list of paths to the existing LanguageTool download directories.
Return type:: List[Path]

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.utils.get_jar_info() → Tuple[Path, Path]¶

Retrieve the path to the Java executable and the LanguageTool JAR file. This function searches for the Java executable in the system’s PATH and locates the LanguageTool JAR file either in a directory specified by an environment variable or in a default download directory.

Raises:

JavaError – If the Java executable cannot be found.
PathError – If the LanguageTool JAR file cannot be found in the specified directory.

Returns:

A tuple containing the path to the Java executable and the path to the LanguageTool JAR file.

Return type:

Tuple[Path, Path]

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.utils.get_language_tool_directory() → Path¶

Get the directory path of the LanguageTool installation. This function checks the download folder for LanguageTool installations, verifies that the folder exists and is a directory, and returns the path to the latest version of LanguageTool found in the directory.

Raises:

NotADirectoryError – If the download folder path is not a valid directory.
FileNotFoundError – If no LanguageTool installation is found in the download folder.

Returns:

The path to the latest version of LanguageTool found in the directory.

Return type:

Path

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.utils.get_language_tool_download_path() → Path¶

Get the download path for LanguageTool. This function retrieves the download path for LanguageTool from the environment variable specified by LTP_PATH_ENV_VAR. If the environment variable is not set, it defaults to a path in the user’s home directory under .cache/language_tool_python. The function ensures that the directory exists before returning it.

Returns:: The download path for LanguageTool.
Return type:: Path

language_tool_python.utils.get_locale_language() → str¶

Get the current locale language. This function retrieves the current locale language setting of the system. It first attempts to get the locale using locale.getlocale(). If that fails, it falls back to using locale.getdefaultlocale(). If both methods fail to provide a valid language code, it returns a default failsafe language code.

Returns:: The language code of the current locale.
Return type:: str

language_tool_python.utils.get_server_cmd(port: int | None = None, config: LanguageToolConfig | None = None) → List[str]¶

Generate the command to start the LanguageTool HTTP server.

Parameters:

port (Optional[int]) – Optional; The port number on which the server should run. If not provided, the default port will be used.
config (Optional[LanguageToolConfig]) – Optional; The configuration for the LanguageTool server. If not provided, default configuration will be used.

Returns:

A list of command line arguments to start the LanguageTool HTTP server.

Return type:

List[str]

Deprecated since version 3.3.0: This function is no longer used internally and will be removed in 4.0.

language_tool_python.utils.kill_process_force(*, pid: int | None = None, proc: Process | None = None) → None¶

Forcefully kills a process and all its child processes. This function attempts to kill a process specified either by its PID or by a psutil.Process object. If the process has any child processes, they will be killed first.

Parameters:

pid (Optional[int]) – The process ID of the process to be killed. Either pid or proc must be provided.
proc (Optional[psutil.Process]) – A psutil.Process object representing the process to be killed. Either pid or proc must be provided.

Raises:

ValueError – If neither pid nor proc is provided.

language_tool_python.utils.parse_url(url_str: str) → str¶

Parse the given URL string and ensure it has a scheme. If the input URL string does not contain ‘http’, ‘http://’ is prepended to it. The function then parses the URL and returns its canonical form.

Parameters:: url_str (str) – The URL string to be parsed.
Returns:: The parsed URL in its canonical form.
Return type:: str

Module contents¶

LanguageTool API for Python.

class language_tool_python.LanguageTag(tag: str, languages: Iterable[str])¶

Bases: object

A class to represent and normalize language tags.

Parameters:

tag (str) – The language tag.
languages (Iterable[str]) – An iterable of supported language tags.

languages: Iterable[str]¶: An iterable of supported language tags.

normalized_tag: str¶: The normalized language tag.

tag: str¶: The language tag to be normalized.

class language_tool_python.LanguageTool(language: str | None = None, mother_tongue: str | None = None, remote_server: str | None = None, new_spellings: List[str] | None = None, new_spellings_persist: bool = True, host: str | None = None, config: Dict[str, Any] | None = None, language_tool_download_version: str = 'latest', proxies: Dict[str, str] | None = None)¶

Bases: object

A class to interact with the LanguageTool server for text checking and correction.

Parameters:

language (Optional[str]) – The language to be used by the LanguageTool server. If None, it will try to detect the system language.
mother_tongue (Optional[str]) – The mother tongue of the user.
remote_server (Optional[str]) – URL of a remote LanguageTool server. If provided, the local server will not be started.
new_spellings (Optional[List[str]]) – Custom spellings to be added to the LanguageTool server.
new_spellings_persist (Optional[bool]) – Whether the new spellings should persist across sessions.
host (Optional[str]) – The host address for the LanguageTool server. Defaults to ‘localhost’.
config (Optional[str]) – Path to a configuration file for the LanguageTool server.
language_tool_download_version (Optional[str]) – The version of LanguageTool to download if needed.
proxies (Optional[Dict[str, str]]) – A dictionary of proxies to use for server requests (e.g., {‘http’: ‘http://proxy:port’, ‘https’: ‘https://proxy:port’}).

check(text: str) → List[Match]¶

Checks the given text for language issues using the LanguageTool server.

Parameters:: text (str) – The text to be checked for language issues.
Returns:: A list of Match objects representing the issues found in the text.
Return type:: List[Match]

check_matching_regions(text: str, pattern: str, flags: int = 0) → List[Match]¶

Check only the parts of the text that match a regex pattern. The returned Match objects can be applied to the original text with language_tool_python.utils.correct().

Parameters:

text – The full text.
pattern – Regular expression defining the regions to check
flags – Regex flags (re.IGNORECASE, re.MULTILINE, etc.)

Returns:

List of Match with offsets adjusted to the original text

Return type:

List[Match]

close() → None¶

Closes the server and performs necessary cleanup operations.

property config: LanguageToolConfig | None¶

Get the server configuration.

This property is read-only as the configuration is set during initialization and cannot be changed while the server is running.

Returns:: The configuration object if set, otherwise None.
Return type:: Optional[LanguageToolConfig]

correct(text: str) → str¶

Corrects the given text by applying language tool suggestions. Applies only the first suggestion for each issue.

Parameters:: text (str) – The text to be corrected.
Returns:: The corrected text.
Return type:: str

disable_spellchecking() → None¶: Disable spellchecking by updating the disabled categories with spell checking categories.

property disabled_categories: Set[str]¶

Get the set of disabled rule categories.

Returns:: A set of disabled category names.
Return type:: Set[str]

property disabled_rules: Set[str]¶

Get the set of disabled rules.

Returns:: A set of disabled rule IDs.
Return type:: Set[str]

enable_spellchecking() → None¶: Enable spellchecking by removing spell checking categories from the disabled categories set. This method updates the disabled_categories attribute by removing any categories that are related to spell checking, which are defined in the _SPELL_CHECKING_CATEGORIES class constant.

property enabled_categories: Set[str]¶

Get the set of enabled rule categories.

Returns:: A set of enabled category names.
Return type:: Set[str]

property enabled_rules: Set[str]¶

Get the set of enabled rules.

Returns:: A set of enabled rule IDs.
Return type:: Set[str]

property enabled_rules_only: bool¶

Get whether only enabled rules should be used.

Returns:: True if using only enabled rules, False otherwise.
Return type:: bool

property host: str¶

Get the local server host address.

This property is read-only as the host address is determined during initialization and cannot be changed while the server is running.

Returns:: The host address (e.g., ‘127.0.0.1’).
Return type:: str

property is_remote: bool¶

Get whether using a remote LanguageTool server.

This property is read-only as the remote status is determined during initialization and cannot be changed while the server is running.

Returns:: True if using a remote server, False if using a local server.
Return type:: bool

property language: LanguageTag¶

Get the language tag associated with the server.

Returns:: The language tag.
Return type:: LanguageTag

property language_tool_download_version: str¶

Get the LanguageTool version to download.

This property is read-only as the version is determined during initialization and the server cannot be re-downloaded with a different version at runtime.

Returns:: The LanguageTool version string.
Return type:: str

property mother_tongue: LanguageTag | None¶

Get the mother tongue language tag.

Returns:: The mother tongue language tag if set, otherwise None.
Return type:: Optional[LanguageTag]

property picky: bool¶

Get whether picky mode is enabled.

Returns:: True if picky mode is enabled, False otherwise.
Return type:: bool

property port: int¶

Get the local server port number.

This property is read-only as the port number is determined during initialization and cannot be changed while the server is running.

Returns:: The port number (e.g., 8081).
Return type:: int

property preferred_variants: Set[str]¶

Get the set of preferred language variants.

Returns:: A set of preferred variant codes.
Return type:: Set[str]

property proxies: Dict[str, str] | None¶

Get the proxies used for server requests.

Returns:: A dictionary of proxies if set, otherwise None.
Return type:: Optional[Dict[str, str]]

property url: str¶

Get the LanguageTool server URL.

This property is read-only as the URL is determined during initialization and cannot be changed while the server is running.

Returns:: The server URL (e.g., ‘http://localhost:8081/v2/’).
Return type:: str

class language_tool_python.LanguageToolPublicAPI(*args: Any, **kwargs: Any)¶

Bases: LanguageTool

A class to interact with the public LanguageTool API. This class extends the LanguageTool class and initializes it with the remote server set to the public LanguageTool API endpoint.

Parameters:

args (Any) – Positional arguments passed to the parent class initializer.
kwargs (Any) – Keyword arguments passed to the parent class initializer.

class language_tool_python.Match(attrib: Dict[str, Any], text: str)¶

Bases: object

Represents a match object that contains information about a language rule violation.

Parameters:

attrib (Dict[str, Any]) –
A dictionary containing various attributes for the match. The dictionary is expected to have the following keys:
- rule (Dict[str, Any]): A dictionary with keys category (which has an id) and id, issueType.
- context (Dict[str, Any]): A dictionary with keys offset and text.
- replacements (List[Dict[str, str]]): A list of dictionaries, each containing a value.
- length (int): The length of the error.
- message (str): The message describing the error.
text (str) – The original text in which the error occurred (the whole text, not just the context).

Example of a match object received from the LanguageTool API :

{
    'message': 'Possible spelling mistake found.',
    'shortMessage': 'Spelling mistake',
    'replacements': [{'value': 'newt'}, {'value': 'not'}, {'value': 'new', 'shortDescription': 'having just been made'}, {'value': 'news'}, {'value': 'foot', 'shortDescription': 'singular'}, {'value': 'root', 'shortDescription': 'underground organ of a plant'}, {'value': 'boot'}, {'value': 'noon'}, {'value': 'loot', 'shortDescription': 'plunder'}, {'value': 'moot'}, {'value': 'Root'}, {'value': 'soot', 'shortDescription': 'carbon black'}, {'value': 'newts'}, {'value': 'nook'}, {'value': 'Lieut'}, {'value': 'coot'}, {'value': 'hoot'}, {'value': 'toot'}, {'value': 'snoot'}, {'value': 'neut'}, {'value': 'nowt'}, {'value': 'Noor'}, {'value': 'noob'}],
    'offset': 8,
    'length': 4,
    'context': {'text': 'This is noot okay. ', 'offset': 8, 'length': 4}, 'sentence': 'This is noot okay.',
    'type': {'typeName': 'Other'},
    'rule': {'id': 'MORFOLOGIK_RULE_EN_US', 'description': 'Possible spelling mistake', 'issueType': 'misspelling', 'category': {'id': 'TYPOS', 'name': 'Possible Typo'}},
    'ignoreForIncompleteSentence': False,
    'contextForSureMatch': 0
}

FOUR_BYTES_POSITIONS: List[int] | None = None¶: The positions of 4-byte encoded characters in the text, registered by the previous match object (kept for optimization purposes if the text is the same).

PREVIOUS_MATCHES_TEXT: str | None = None¶: The text of the previous match object.

category: str¶: The category of the rule that was violated.

context: str¶: The context in which the error occurred.

error_length: int¶: The length of the error.

get_line_and_column(original_text: str) → Tuple[int, int]¶

Returns the line and column number of the error in the context.

Parameters:: original_text (str) – The original text in which the error occurred. We need this to calculate the line and column number, because the context has no more newline characters.
Returns:: A tuple containing the line and column number of the error.
Return type:: Tuple[int, int]

property matched_text: str¶

Returns the substring from the context that corresponds to the matched text.

Returns:: The matched text from the context.
Return type:: str

message: str¶: The message describing the error.

offset: int¶: The offset of the error.

offset_in_context: int¶: The offset of the error in the context.

replacements: List[str]¶: A list of suggested replacements for the error.

rule_id: str¶: The ID of the rule that was violated.

rule_issue_type: str¶: The issue type of the rule that was violated.

select_replacement(index: int) → None¶

Select a single replacement suggestion based on the given index and update the replacements list, leaving only the selected replacement.

Parameters:

index (int) – The index of the replacement to select.

Raises:

ValueError – If there are no replacement suggestions.
ValueError – If the index is out of the valid range.