# How readability_scorer.py Calculates Flesch Reading Ease and Flesch-Kincaid Grade Level

> Discover how readability_scorer.py calculates Flesch Reading Ease and Flesch-Kincaid Grade Level using the textstat library. Get clear scores for your content.

- Repository: [Craig/seomachine](https://github.com/TheCraigHewitt/seomachine)
- Tags: how-to-guide
- Published: 2026-03-12

---

**The `ReadabilityScorer` class delegates Flesch calculations to the `textstat` library, calling `textstat.flesch_reading_ease()` and `textstat.flesch_kincaid_grade()` on cleaned content to return scores rounded to one decimal place.**

The TheCraigHewitt/seomachine repository evaluates content complexity through a dedicated readability module. In [`data_sources/modules/readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/readability_scorer.py), the `ReadabilityScorer` class orchestrates the calculation of Flesch Reading Ease and Flesch-Kincaid Grade Level without implementing the linguistic formulas itself. Instead, it leverages the third-party `textstat` library to generate these metrics after sanitizing the input text.

## Content Preparation Pipeline

Before calculating either metric, the scorer sanitizes raw input to ensure accurate linguistic analysis. The `analyze()` method calls `_clean_content()` to strip markdown headers, hyperlinks, code blocks, and excess whitespace. This preprocessing step removes formatting artifacts that could artificially inflate syllable counts or sentence lengths, ensuring the subsequent Flesch calculations reflect actual readable content.

## Inside the _calculate_metrics Method

The actual computation happens in the private `_calculate_metrics` method of [`readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/readability_scorer.py). This method receives the pre-cleaned text string and interfaces with the `textstat` library to produce both readability scores.

### Calculating Flesch Reading Ease

For the Flesch Reading Ease score, the code executes `textstat.flesch_reading_ease(text)` (see lines 90-92). This function analyzes the total number of syllables, words, and sentences to return a score ranging from 0 to 100, where higher values indicate easier reading material. The `ReadabilityScorer` rounds this result to one decimal place and stores it in the internal `metrics` dictionary under the key `'flesch_reading_ease'`.

### Calculating Flesch-Kincaid Grade Level

Immediately following the ease calculation, the method calls `textstat.flesch_kincaid_grade(text)` (lines 92-93) to determine the U.S. school-grade level required to understand the text. Using similar linguistic inputs—total syllables, word count, and sentence count—this function computes the educational grade equivalent. The result is also rounded to one decimal place and stored under `'flesch_kincaid_grade'`.

Because the heavy linguistic processing is delegated to `textstat`, [`readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/readability_scorer.py) does not maintain its own implementations of these algorithms; it simply forwards the cleaned text and captures the library's output.

## Integration with the Analysis Workflow

The `score_readability()` function serves as the typical entry point for external callers. It instantiates `ReadabilityScorer`, processes content through the cleaning and calculation pipeline, and returns a structured dictionary. The Flesch Reading Ease and Flesch-Kincaid Grade Level values are accessible under the `readability_metrics` key, ready for use in overall scoring, status assessment, and recommendation generation.

## Practical Implementation Example

```python
from data_sources.modules.readability_scorer import score_readability

article = """

# Why Good Sleep Matters

Sleep affects everything you do—thinking, feeling, and physical health. 
Most adults need 7‑9 hours each night. This guide explains why and how to improve it.
"""

result = score_readability(article)

print("Flesch Reading Ease :", result["readability_metrics"]["flesch_reading_ease"])
print("Flesch‑Kincaid Grade:", result["readability_metrics"]["flesch_kincaid_grade"])

```

This example demonstrates how to calculate Flesch Reading Ease and Flesch-Kincaid Grade Level using the module's high-level interface. The output shows typical values: a Reading Ease score around 68.4 and a Grade Level around 8.2 for standard web content.

## Dependencies and Source Files

The readability functionality depends on the `textstat` package declared in [`data_sources/requirements.txt`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/requirements.txt). The core implementation resides entirely within [`data_sources/modules/readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/readability_scorer.py), specifically in the private `_calculate_metrics` method that orchestrates the calls to `textstat.flesch_reading_ease()` and `textstat.flesch_kincaid_grade()`.

## Summary

- The `ReadabilityScorer` class in [`data_sources/modules/readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/readability_scorer.py) handles all readability calculations for the repository.
- Both Flesch metrics are computed using the third-party `textstat` library rather than custom formula implementations.
- Content is pre-processed via `_clean_content()` to remove markdown and formatting artifacts before analysis.
- Flesch Reading Ease scores (0-100) are generated via `textstat.flesch_reading_ease()` (lines 90-92).
- Flesch-Kincaid Grade Level is generated via `textstat.flesch_kincaid_grade()` (lines 92-93).
- Results are rounded to one decimal place and stored in a metrics dictionary for downstream SEO analysis pipelines.

## Frequently Asked Questions

### What library does readability_scorer.py use to calculate Flesch Reading Ease?

The module uses the `textstat` Python library to calculate Flesch Reading Ease and Flesch-Kincaid Grade Level. You can find this dependency listed in [`data_sources/requirements.txt`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/requirements.txt). The `ReadabilityScorer` class imports this library and calls its specific functions rather than implementing the linguistic formulas manually in the source code.

### Does the scorer modify the standard Flesch formulas?

No, the module does not alter the formulas. It delegates directly to `textstat.flesch_reading_ease()` and `textstat.flesch_kincaid_grade()` without modification. The only transformation applied is rounding the final output to one decimal place before storing it in the results dictionary under `'flesch_reading_ease'` and `'flesch_kincaid_grade'`.

### How does the scorer handle markdown or HTML content?

The `analyze()` method first calls `_clean_content()` to strip markdown headers, links, code blocks, and excess whitespace. This ensures that formatting syntax does not interfere with the syllable and sentence counts used by the Flesch algorithms, preventing artificially inflated complexity scores.

### What is the entry point for calculating readability scores in SEO Machine?

The primary entry point is the `score_readability()` function exported from [`data_sources/modules/readability_scorer.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/readability_scorer.py). This function instantiates the `ReadabilityScorer` class, runs the full analysis pipeline including content cleaning and metric calculation, and returns a dictionary containing both the Flesch Reading Ease and Flesch-Kincaid Grade Level under the `readability_metrics` key.