readability-scorer

可读性评分器

使用行业标准公式分析文本可读性。获取年级估算、复杂度指标以及提升清晰度的建议。

快速开始

from scripts.readability_scorer import ReadabilityScorer

# Score text
scorer = ReadabilityScorer()
scores = scorer.analyze("Your text to analyze goes here.")
print(f"Grade Level: {scores['grade_level']}")
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']}")

功能

• 多种公式：Flesch-Kincaid、Gunning Fog、SMOG、Coleman-Liau、ARI
• 年级水平：美国年级水平估算
• 阅读易读度：0-100 分的易读度评分
• 文本统计：单词、句子、音节、复杂单词
• 批量分析：处理多个文档
• 对比：比较不同文本的可读性

API 参考

初始化

scorer = ReadabilityScorer()

分析

scores = scorer.analyze(text)
# Returns:
# {
#     'flesch_reading_ease': 65.2,
#     'flesch_kincaid_grade': 8.1,
#     'gunning_fog': 10.2,
#     'smog_index': 9.5,
#     'coleman_liau': 9.8,
#     'ari': 8.4,
#     'grade_level': 8.5,  # Average
#     'reading_time_minutes': 2.3,
#     'stats': {
#         'words': 250,
#         'sentences': 15,
#         'syllables': 380,
#         'complex_words': 25,
#         'avg_words_per_sentence': 16.7,
#         'avg_syllables_per_word': 1.52
#     }
# }

单项评分

# Get specific scores
fre = scorer.flesch_reading_ease(text)
fkg = scorer.flesch_kincaid_grade(text)
fog = scorer.gunning_fog(text)
smog = scorer.smog_index(text)

批量分析

texts = [text1, text2, text3]
results = scorer.analyze_batch(texts)

# From files
results = scorer.analyze_files(["doc1.txt", "doc2.txt"])

对比

# Compare two texts
comparison = scorer.compare(text1, text2)
print(f"Text 1 grade: {comparison['text1']['grade_level']}")
print(f"Text 2 grade: {comparison['text2']['grade_level']}")

CLI 用法

# Analyze text
python readability_scorer.py --text "Your text here"

# Analyze file
python readability_scorer.py --input document.txt

# Compare files
python readability_scorer.py --compare doc1.txt doc2.txt

# Batch analyze directory
python readability_scorer.py --input-dir ./docs --output report.csv

# Specific formula only
python readability_scorer.py --input doc.txt --formula flesch

CLI 参数

参数	描述	默认值
--text	要分析的文本	-
--input	输入文件	-
--input-dir	文件目录	-
--output	输出文件（json/csv）	-
--compare	对比两个文件	-
--formula	指定公式	all

评分解读

Flesch 阅读易读度

评分	难度	年级水平
90-100	非常容易	5 年级
80-89	容易	6 年级
70-79	较容易	7 年级
60-69	标准	8-9 年级
50-59	较难	10-12 年级
30-49	困难	大学
0-29	非常困难	大学毕业

年级水平量表

年级	受众
1-5	小学
6-8	初中
9-12	高中
13-16	大学
17+	研究生水平

示例

分析博客文章

scorer = ReadabilityScorer()

blog_post = """
Writing clear content is essential for engaging readers.
Short sentences help. Simple words work best.
Your audience will thank you for making things easy to understand.
"""

scores = scorer.analyze(blog_post)
print(f"Flesch Reading Ease: {scores['flesch_reading_ease']:.1f}")
print(f"Grade Level: {scores['grade_level']:.1f}")
print(f"Reading Time: {scores['reading_time_minutes']:.1f} minutes")

if scores['grade_level'] > 8:
    print("Consider simplifying for a wider audience.")

对比文档版本

scorer = ReadabilityScorer()

original = open("original.txt").read()
simplified = open("simplified.txt").read()

comparison = scorer.compare(original, simplified)

print("Original:")
print(f"  Grade Level: {comparison['text1']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text1']['flesch_reading_ease']:.1f}")

print("\nSimplified:")
print(f"  Grade Level: {comparison['text2']['grade_level']:.1f}")
print(f"  Flesch Ease: {comparison['text2']['flesch_reading_ease']:.1f}")

improvement = comparison['text1']['grade_level'] - comparison['text2']['grade_level']
print(f"\nImprovement: {improvement:.1f} grade levels easier")

批量分析文档

scorer = ReadabilityScorer()
import os

results = []
for filename in os.listdir("./docs"):
    if filename.endswith(".md"):
        text = open(f"./docs/{filename}").read()
        scores = scorer.analyze(text)
        results.append({
            'file': filename,
            'grade': scores['grade_level'],
            'ease': scores['flesch_reading_ease']
        })

# Sort by difficulty
results.sort(key=lambda x: x['grade'], reverse=True)

print("Documents by Difficulty:")
for r in results:
    print(f"  {r['file']}: Grade {r['grade']:.1f}")

依赖项

nltk>=3.8.0

局限性

• 仅支持英语
• 公式针对散文设计（可能不适用于列表、代码等内容）
• 音节计数为估算值（可能存在轻微误差）
• 不评估理解能力，只评估表层复杂度