API Reference¶

HTTP API¶

Python API wrapper for the languagetool REST API.

Simple usage:

>>> from pylanguagetool import api
>>> api.check(
...     'This is a example',
...     api_url='https://languagetool.org/api/v2/',
...     lang='en-US',
... )

pylanguagetool.api.check(input_text: str, api_url: str, lang: str, pwl: list[str], mother_tongue: str | None = None, preferred_variants: str | None = None, enabled_rules: str | None = None, disabled_rules: str | None = None, enabled_categories: str | None = None, disabled_categories: str | None = None, enabled_only: bool = False, picky: bool = False, verbose: bool = False, username: str | None = None, api_key: str | None = None)[source]¶

Check given text and return API response as a dictionary.

Parameters:

input_text (str) – Plain text that will be checked for spelling mistakes.
api_url (str) – API base url, e.g. https://languagetool.org/api/v2/
lang –
Language of the given text as RFC 3066 language code. For example en-GB or de-AT. auto is a valid value too and will cause the language to be detected automatically.
mother_tongue –
Native language of the author as RFC 3066 language code.
preferred_variants (str) – Comma-separated list of preferred language variants. The language detector used with language=auto can detect e.g. English, but it cannot decide whether British English or American English is used. Therefore, this parameter can be used to specify the preferred variants like en-GB and de-AT. Only available with language=auto.
enabled_rules (str) – Comma-separated list of IDs of rules to be enabled
disabled_rules (str) – Comma-separated list of IDs of rules to be disabled.
enabled_categories (str) – Comma-separated list of IDs of categories to be enabled.
disabled_categories (str) – Comma-separated list of IDs of categories to be disabled.
enabled_only (bool) – If True, only the rules and categories whose IDs are specified with enabledRules or enabledCategories are enabled. Defaults to False.
picky (bool) – If enabled, addition rules are activated.
verbose (bool) – If True, a more verbose output will be printed. Defaults to False.
pwl (list[str]) – Personal world list. A custom dictionary of words that should be excluded from spell checking errors.
username (str) – For Premium API
api_key (str) – For Premium API

Returns:

A dictionary representation of the JSON API response. The most notable key is matches, which contains a list of all spelling mistakes that have been found.

E.g.:

{
    "language": {
        "name": "English (GB)",
        "code": "en-GB",
        "detectedLanguage": {
            "name": "English (GB)",
            "code": "en-GB",
            "confidence": 0.561,
            "source": "fasttext",
        },
    },
    "sentenceRanges": [[0, 17]],
    "extendedSentenceRanges": [
        {"from": 0, "to": 17, "detectedLanguages": [{"language": "en", "rate": 1.0}]}
    ],
    "matches": [
        {
            "context": {"text": "This is a example", "offset": 8, "length": 1},
            "contextForSureMatch": 1,
            "ignoreForIncompleteSentence": False,
            "length": 1,
            "message": "Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.",
            "offset": 8,
            "replacements": [{"value": "an"}],
            "rule": {
                "category": {"id": "MISC", "name": "Miscellaneous"},
                "description": "Use of 'a' vs. 'an'",
                "id": "EN_A_VS_AN",
                "issueType": "misspelling",
                "urls": [
                    {
                        "value": "https://languagetool.org/insights/post/indefinite-articles/"
                    }
                ],
            },
            "sentence": "This is a example",
            "shortMessage": "Wrong article",
            "type": {"typeName": "Other"},
        }
    ],
    "software": {
        "apiVersion": 1,
        "buildDate": "2024-09-27 11:27:57 +0200",
        "version": "6.5",
        "name": "LanguageTool",
        "premium": False,
        "premiumHint": "You might be missing errors only the Premium version can find. Contact us at support<at>languagetoolplus.com.",
        "status": "",
    },
    "warnings": {"incompleteResults": False},
}

Return type:

dict

pylanguagetool.api.get_languages(api_url: str) → list[dict[str, str]][source]¶

Return supported languages as a list of dictionaries.

Parameters:

api_url (str) – API base url.

Returns:

Supported languages as a list of dictionaries.

Each dictionary contains three keys, name, code and longCode:

{
    "name":"English (GB)",
    "code":"en",
    "longCode":"en-GB"
}

Return type:

list[dict]

CLI¶

A python library and CLI tool for the LanguageTool JSON API.

pylanguagetool.cli.get_clipboard() → str[source]¶

Return text stored in the operating system’s clipboard.

Returns:: Text stored in the operating system’s clipboard.
Return type:: str

pylanguagetool.cli.get_input_text(config: dict[str, Any]) → list[tuple[str, str | None]][source]¶

Return text from stdin, clipboard or file.

Returns:: A tuple contain of the text and an optional filename. If the text does not come from a file, the filename part of the tuple will be none.
Return type:: tuple[Optional[str], Optional[str]]

pylanguagetool.cli.init_config() → tuple[dict[str, Any], ArgumentParser][source]¶: Create ArgumentParser object

pylanguagetool.cli.main() → None[source]¶: The main CLI entry point.

pylanguagetool.cli.print_errors(response, api_url: str, print_color: bool = True, rules: bool = False, rule_categories: bool = False, explain_rule: bool = False) → None[source]¶: Print output from API response

Converters¶

Support spellchecking various file formats by converting them to plain text

pylanguagetool.converters.convert(source: str, texttype: str | None) → str[source]¶

Convert files of various types to plaintext

Parameters:

texttype (str) – file extension of the input file
source (str) – content of the input file

Returns:

plaintext output

Return type:

str

pylanguagetool.converters.html2text(html: str) → str[source]¶

convert HTML to plaintext by parsing it with BeautifulSoup and removing code

Parameters:: html (str) – HTML string
Returns:: plaintext
Return type:: str

pylanguagetool.converters.ipynb2markdown(ipynb: str) → str[source]¶

Extract Markdown cells from iPython Notebook

Parameters:: ipynb (str) – iPython notebook JSON file
Returns:: Markdown
Return type:: str

pylanguagetool.converters.markdown2html(markdown: str) → str[source]¶

convert Markdown to HTML via markdown2

Parameters:: markdown (str) – Markdown text
Returns:: HTML
Return type:: str

pylanguagetool.converters.rst2html(rst: str) → str[source]¶

convert reStructuredText to HTML with docutils

Parameters:: rst (str) – reStructuredText
Returns:: HTML
Return type:: str

pylanguagetool.converters.transifexjson2txt(jsondata: str) → str[source]¶

extract translations from Transifex JSON file

Parameters:: jsondata (str) – Transifex export file
Returns:: Plaintext translations
Return type:: str

pylanguagetool.converters.xliff2txt(source: str) → str[source]¶

extract translations from XLIFF file

Parameters:: source (str) – XLIFF XML string
Returns:: Plaintext translations
Return type:: str