Examples¶

This page provides practical examples for using language_tool_python. For advanced patterns (resource management, client/server, error handling, pinning the LT version) see Advanced usage. For CLI usage see Command-line interface. For environment variables see Environment variables. For local server configuration see Local server configuration.

Basic usage¶

Checking text for errors¶

Use LanguageTool to check a piece of text. The check() method returns a list of Match objects, each describing a detected issue.

import language_tool_python

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

print(len(matches))
# → 2
print(matches[0].message)
# → 'Use "an" instead of "a" if the following word starts with a vowel sound'
print(matches[0].replacements)
# → ['an']
print(matches[0].offset)
# → 16

Correcting text automatically¶

correct() applies the first suggestion for each detected issue and returns the fixed text.

import language_tool_python

with language_tool_python.LanguageTool("en-US") as tool:
    corrected = tool.correct("A sentence with a error in the Hitchhiker's Guide tot he Galaxy")

print(corrected)
# → A sentence with an error in the Hitchhiker's Guide to the Galaxy

You can also call correct() directly with a custom list of Match objects if you need to filter them first.

import language_tool_python
from language_tool_python.utils import correct

with language_tool_python.LanguageTool("en-US") as tool:
    text = "This are wrong."
    matches = tool.check(text)

print([match.rule_id for match in matches])
# → ['THIS_NNS', 'THAT_SOUND_GREAT']
print(correct(text, matches))
# → These is wrong.

matches = [m for m in matches if m.rule_id != "THIS_NNS"]
print(correct(text, matches))
# → This is wrong.
# Ignore the first match

Applying a specific suggestion¶

correct() always picks the first suggestion. To choose a different one, call select_replacement() before passing the match to correct():

import language_tool_python
from language_tool_python.utils import correct

text = "There is a bok on the table."
with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check(text)

print(matches[0].replacements)
# → ['BOK', 'OK', 'book', 'box', 'boy', 'Bob', 'bow', 'beak', ...]
matches[0].select_replacement(2)  # pick the third suggestion instead of the first
patched = correct(text, matches)
print(patched)
# → There is a book on the table.

Using the public API (no local server)¶

LanguageToolPublicAPI connects to the hosted LanguageTool service instead of starting a local Java server. No Java installation is required, but requests are subject to rate limits.

import language_tool_python

with language_tool_python.LanguageToolPublicAPI("en-US") as tool:
    matches = tool.check("This are wrong.")

print(len(matches))
# → 2

Note

The public API is subject to rate limits. If you need to check multiple texts or large documents, consider using LanguageTool with a local server instead, or authenticating with a premium key (see Advanced usage).

Checking only specific regions of text¶

check_matching_regions() restricts checking to the parts of the text that match a regular expression. This is useful when the text contains markup, code blocks, or other sections that should be skipped.

import language_tool_python
from language_tool_python.utils import correct

text = 'He seid "I has a problem" but she replied "It are fine".'

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check_matching_regions(
        text,
        r'"[^"]*"',  # only check text inside double quotes
    )

print(correct(text, matches))
# → He seid "I have a problem" but she replied "It is fine".
# "seid" is not corrected because it is outside the quoted regions.

Controlling rules¶

Disabling specific rules¶

Pass rule IDs to disabled_rules to suppress individual rules, or call disable_spellchecking() to turn off all spell-check categories at once.

import language_tool_python

text = "Thiss is false."

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check(text)
    print(len(matches))
    # → 1

with language_tool_python.LanguageTool("en-US") as tool:
    tool.disabled_rules = {"MORFOLOGIK_RULE_EN_US"}
    matches = tool.check(text)
    print(len(matches))
    # → 0
    # The rule "MORFOLOGIK_RULE_EN_US" is disabled, so the spelling error is ignored.

with language_tool_python.LanguageTool("en-US") as tool:
    tool.disable_spellchecking()
    matches = tool.check(text)
    print(len(matches))
    # → 0
    # The spellchecking is disabled, so the spelling error is ignored.

Enabling only specific rules¶

Set enabled_rules_only to True to run exclusively the rules listed in enabled_rules.

import language_tool_python

text = "This are wrong."

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check(text)
    print([match.rule_id for match in matches])
    # → ['THIS_NNS', 'THAT_SOUND_GREAT']
    print(tool.correct(text))
    # → These is wrong.

with language_tool_python.LanguageTool("en-US") as tool:
    tool.enabled_rules = {"THIS_NNS"}
    tool.enabled_rules_only = True
    print(tool.correct(text))
    # → These are wrong.
    # Only the THIS_NNS rule is applied

Controlling categories¶

Use disabled_categories and enabled_categories to enable or disable entire rule categories at once. Here is a list of all categories.

import language_tool_python

text = "I wentt to new york last week."

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check(text)
    print([match.category for match in matches])
    # → ['TYPOS', 'CASING']
    print(tool.correct(text))
    # → I went to New York last week.

with language_tool_python.LanguageTool("en-US") as tool:
    tool.enabled_categories = {"CASING"}
    tool.enabled_rules_only = True
    matches = tool.check(text)
    print([match.category for match in matches])
    # → ['CASING']
    print(tool.correct(text))
    # → I wentt to New York last week.

Picky mode (stricter checking)¶

Enable picky for additional style rules that are too strict for casual writing.

Preferred language variants¶

preferred_variants lets you specify which dialect to prefer when you use the “auto” language. LanguageTool can detect the language that is used in the text, but you have to specify variants in case of a language with multiple dialects (e.g. English) is detected.

import language_tool_python

text = "The colour of the sky."

with language_tool_python.LanguageTool("auto") as tool:
    tool.preferred_variants = {"en-US"}
    print(tool.correct(text))
    # → The color of the sky.

with language_tool_python.LanguageTool("auto") as tool:
    tool.preferred_variants = {"en-GB"}
    print(tool.correct(text))
    # → The colour of the sky.

Mother tongue detection¶

Setting mother_tongue helps LanguageTool detect false friends (words that look similar across two languages but carry different meanings). It works only with ngrams data installed (see Local server configuration).

import language_tool_python

config = {
    "languageModel": "/path/to/ngrams"
}

with language_tool_python.LanguageTool("en-US", config=config) as tool:
    matches = tool.check("My handy is broken.")
    print(matches)
    # → []

with language_tool_python.LanguageTool("en-US", mother_tongue="de", config=config) as tool:
    matches = tool.check("My handy is broken.")
    print(matches[0].message)
    # → “handy” (English) means “praktisch”, “handlich” (German). Did you maybe mean “cell phone”, “mobile phone”?

Classifying matches¶

classify_matches() categorises a list of matches as:

CORRECT - no matches found.
FAULTY - at least one match has replacement suggestions.
GARBAGE - matches exist but none have suggestions (unrecognisable input).

import language_tool_python
from language_tool_python.utils import classify_matches

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check("This sentence is correct.")
    print(classify_matches(matches))
    # → TextStatus.CORRECT
    matches = tool.check("This are wrong.")
    print(classify_matches(matches))
    # → TextStatus.FAULTY
    matches = tool.check("fnekknfzn")
    print(classify_matches(matches))
    # → TextStatus.GARBAGE

Custom spellings¶

Pass a list of words via new_spellings to add them to the local LanguageTool dictionary. By default they persist across sessions (new_spellings_persist=True).

import language_tool_python

with language_tool_python.LanguageTool(
    "en-US",
) as tool:
    matches = tool.check("Welcome to the compani.")
    print(len(matches))
    # → 1
    # "compani" is not a known word, so LanguageTool suggests "company" as a correction

with language_tool_python.LanguageTool(
    "en-US",
    new_spellings=["compani"],
    new_spellings_persist=False,
) as tool:
    matches = tool.check("Welcome to the compani.")
    print(len(matches))
    # → 0
    # "compani" is now a known word, so LanguageTool does not suggest any corrections

Pass new_spellings_persist=False to keep the words for the current session only, they are removed when close() is called.

Using a remote LanguageTool server¶

Point LanguageTool at a self-hosted LanguageTool server with the remote_server parameter.

import language_tool_python

with language_tool_python.LanguageTool(
    "en-US",
    remote_server="http://my-languagetool-server:8081",
) as tool:
    print(tool.correct("I has a problem."))
    # → I have a problem.

You can also route requests through an HTTP proxy:

import language_tool_python

with language_tool_python.LanguageTool(
    "en-US",
    remote_server="http://my-languagetool-server:8081",
    proxies={"http": "http://proxy:3128", "https": "http://proxy:3128"},
) as tool:
    print(tool.correct("I has a problem."))
    # → I have a problem

Note

proxies can only be used together with remote_server. Passing proxies without remote_server raises ValueError.

Inspecting a Match object¶

Each Match object exposes the following attributes:

Attribute	Description
`rule_id`	Identifier of the triggered rule (e.g. `"MORFOLOGIK_RULE_EN_US"`).
`message`	Human-readable description of the issue.
`replacements`	Ordered list of suggested corrections (may be empty).
`offset`	Start character position in the original text.
`error_length`	Number of characters covered by the error.
`context`	Short excerpt of text surrounding the error.
`offset_in_context`	Position of the error within `context`.
`category`	Rule category (e.g. `"TYPOS"`, `"GRAMMAR"`).
`rule_issue_type`	Issue type string (e.g. `"misspelling"`, `"grammar"`).
`sentence`	Full sentence containing the error.

import language_tool_python

with language_tool_python.LanguageTool("en-US") as tool:
    matches = tool.check("This are wrong.")

m = matches[0]
print(m.rule_id)
# → THIS_NNS
print(m.message)
# → The singular demonstrative pronoun ‘this’ does not agree with the plural verb ‘are’. Did you mean “these”?
print(m.replacements)
# → ['These']
print(m.offset)
# → 0
print(m.error_length)
# → 4
print(m.context)
# → 'This are wrong.'
print(m.offset_in_context)
# → 0
print(m.category)
# → GRAMMAR
print(m.rule_issue_type)
# → grammar
print(m.sentence)
# → 'This are wrong.'