Python client

Two packages on PyPI: kotoshu, the client, and kotoshu-native, the Rust engine as a maturin wheel. Same result types either way.

Install

pip install kotoshu              # the HTTP client (pure Python)
pip install kotoshu-native       # optional: the Rust engine as a wheel (macOS arm64, more platforms coming)

Python 3.10+. The client is a thin, dependency-light wrapper; the native wheel embeds the Rust engine for offline checking.

Quick start — over HTTP

Point the client at a running kotoshu-server:

from kotoshu import Client

client = Client("http://127.0.0.1:9292", language="en")

result = client.check("helo wrold", language="en")
for err in result.errors:
print(err.word, "->", err.top_suggestions[:3])

for sug in client.suggest("recieve", max_suggestions=3):
print(sug.word, round(sug.confidence, 2))

print(client.correct("hello", language="en"))

helo -> ['hello', 'help', 'hell']
wrold -> ['world', 'wold', 'weld']
receive 1.0
relieve 0.91
recife 0.5
True

Offline — the native engine

With kotoshu-native installed, checking runs in-process against local Hunspell files — no server, no network:

from kotoshu.native import dictionary

d = dictionary("en_US.aff", "en_US.dic")   # paths to Hunspell sources

d.correct("hello")                       # True
d.correct("helo")                        # False
d.suggest("hlelo", max_suggestions=3)
# [Suggestion(word="hello", distance=1, confidence=1.0, source="edit_distance"),
#  Suggestion(word="halo",  distance=1, confidence=0.5, source="phonetic"),
#  Suggestion(word="heel",  distance=1, confidence=0.5, source="phonetic")]

Choosing a backend

KOTOSHU_BACKEND — or nothing at all:

kotoshu.backend() reports the backend in effect. The offline engine is word-level — correct and suggest — while the HTTP client also checks whole documents and detects language. Errors are typed: KotoshuError as the base, ResourceNotSetupError for the 422 the server returns when a language has not been set up.

Verified 2026-09-05 — both quick starts executed against kotoshu 0.1.0 and kotoshu-native 0.1.0 on Python 3.10, server from source. Registry: kotoshu on PyPI · kotoshu-native on PyPI · kotoshu-python repo