readscore

Installation

pip install readscore

Quick Start

Pass text to Readability, then call any metric method. Each method returns a typed result object.

from readscore import Readability

text = """
Plain language means writing that your audience can understand the first time
they read it. Short sentences help. Common words help more. You do not need to
simplify your ideas — just the way you express them. Jargon and long sentences
slow people down and make them feel excluded. Simple writing is not dumbed-down
writing. It is respectful writing. Federal agencies, healthcare providers, and
legal teams use readability formulas to check whether documents reach their
intended audience. Running a check takes seconds. readscore gives you nine
proven formulas in one Python library with a consistent API.
"""

r = Readability(text)

flesch = r.flesch()
print(flesch.score)        # ~74.3
print(flesch.ease)         # 'fairly_easy'
print(flesch.grade_level)  # '7'

fk = r.flesch_kincaid()
print(fk.score)            # ~7.2
print(fk.grade_level)      # '7'

# All nine metrics use the same pattern
r.ari()
r.smog()
r.gunning_fog()
r.dale_chall()
r.coleman_liau()
r.linsear_write()
r.spache()

# Access raw text statistics
print(r.stats.num_words)              # 107
print(r.stats.avg_syllables_per_word) # 1.4

Minimum text length

readscore defaults to a minimum of 100 words. Passing shorter text raises a ValueError. You can lower the threshold with Readability(text, min_words=50), but scores become less reliable on short texts. SMOG also requires at least 30 sentences.

What you get

Nine proven formulas

ARI, Coleman-Liau, Dale-Chall, Flesch, Flesch-Kincaid, Gunning Fog, Linsear Write, SMOG, and Spache. Each has its own page explaining what it measures, when to use it, and where it falls short.

Typed, structured results

Every metric returns a frozen dataclass. Fields are documented. Results are comparable by score. No parsing strings or digging through raw dicts.

Text statistics included

r.stats gives you word count, sentence count, syllable count, polysyllabic word count, and more — computed once at construction and shared across all metric calls.

Extensible

Subclass BaseMeasure to add your own metric. It receives the same StatSummary the built-in metrics use and fits the same interface.

Which metric should I use? A plain-language guide to all nine formulas — what they measure, when to use them, and how their scores compare on the same text.

Built for plain language work

readscore is the scoring engine behind Plain License tools, including the in-development plainr CLI. It is designed to run in CI pipelines, scripts, and anywhere Python runs.

The library is a modernized fork of py-readability-metrics by Carmine DiMascio.