Skip to content

Python Readability Package: 133 Tests, Strict Types

4 min read Notes

Python Readability Package: 133 Tests, Strict Types

Python is where text ends up after the CMS, the export and the spreadsheet. A python readability package that has to live there needs two things beyond correct arithmetic: a type checker that passes and tests that do not flake.

Code: ReadSightPy, MIT licensed.

Python 3.10, two runtime dependencies (regex, platformdirs), 133 tests, mypy in strict mode, ruff clean.

Install and call

from readsight import ReadSight

rs = ReadSight("en-us")

for formula in rs.get_supported_formulas():
    result = rs.score(formula, text)
    # result.score, result.grade_level, result.interpretation

The API is snake_case and returns objects rather than tuples, so a result can be logged, serialised or asserted without unpacking. FormulaResult carries the score, the grade level, the interpretation, the formula name, the language code and a dict of intermediate values.

Intermediate values matter in a pipeline. When a document scores badly, inputs says whether sentences or syllables caused it, and that answer decides the ticket.

The language decides the formula set

get_supported_formulas() returns what the language can answer: nine for en-us, eleven for es, eight for de-1996, five universal ones for th. Five formulas (Gunning Fog, SMOG, Coleman-Liau, ARI, LIX) count letters and syllables and work everywhere.

Twelve formulas carry published coefficients: Flesch Reading Ease and Flesch-Kincaid across twelve languages, Wiener Sachtextformel in four variants for German, Gulpease for Italian, FOG-PL for Polish, OSMAN for Arabic, four Spanish formulas.

Syllables: three modes, one honest note

tex is the default for 80 languages and uses the Liang algorithm over hyphens from hyph-utf8. composite covers en-us and en-gb. heuristic covers ru, uk, be and bg, where one vowel is one syllable and TeX patterns over-count.

split_word() always returns exact hyphenation points. split_syllables() may return a heuristic split. Syllable counts are exact in heuristic and composite mode, approximate in tex mode, and the readme says which is which instead of implying uniform precision.

Configuration and cache

Data directory, language directory and cache directory are configurable globally through Config or per instance through constructor arguments. Compiled patterns land in platformdirs.user_cache_dir(), which means the right path on Linux, macOS and Windows without a shell script.

For a container that is the difference between a warm cache baked into the image and a first run that parses 86 pattern files.

What strict typing buys

mypy --strict with zero errors and ruff with zero findings are not decoration. A pipeline that scores ten thousand documents calls the same three methods a hundred thousand times, and a wrong type in one branch produces a score for the wrong language rather than a crash.

The test suite runs 133 tests: hyphenation, syllable counts, text splitting, every formula, grade-level interpretation and parity with the PHP reference. Golden vectors make the last one a definition rather than a comparison of opinions.

Performance that fits the job

About 0.05 ms for a single word, about 1 ms for a 45-word text, 10 ms to build an engine from cache and 60 ms for a German engine on first load.

Nothing here wins a benchmark against a compiled language, and it does not have to. The database read dominates a batch, and a millisecond per document means the scorer is not the bottleneck.

One more practical note: build one engine per language and reuse it. Creating an engine inside a loop is the mistake that turns a five-minute job into an hour.

Where it stops

No structure parsing, no grammar, no judgement about whether the argument works. Dale-Chall and Spache estimate difficult words from syllable counts, and the readme calls that an estimate.

Related: rust readability crate for the same engine with data inside the binary, and nodejs readability for the JavaScript build.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation