textly — Text Analytics for Python

textly is a Python library for computing readability scores, grade levels, and text complexity metrics for English text. It works with any prose but is particularly tuned for scientific and technical writing.

This library is built upon the foundation of the scireadability Python library, but behaves differently.

Installation

pip install textly

Quick start

import textly

text = (
    "Within the heterogeneous canopy of the Amazonian rainforest, "
    "a fascinating interspecies interaction manifests between "
    "Cephalotes atratus, a species of arboreal ant, and Epiphytes "
    "dendrobii, a genus of epiphytic orchids."
)

textly.flesch_reading_ease(text)
textly.flesch_kincaid_grade(text)
textly.smog_index(text)
textly.coleman_liau_index(text)
textly.automated_readability_index(text)
textly.dale_chall_readability_score(text)
textly.gunning_fog(text)
textly.text_standard(text)          # consensus grade across all formulas
textly.reading_time(text)           # in seconds (default 200 WPM)

What makes textly different

• CMUdict-driven syllable counting — uses the Carnegie Mellon Pronouncing Dictionary, taking the minimum syllable count when multiple pronunciations exist.
• Custom syllable dictionary — user-editable overrides for domain-specific terms, jargon, and species names.
• Regex fallback — a refined heuristic counter tuned for scientific suffixes, agreeing with CMUdict ~91% of the time.
• Token-based difficult word rates — formulas like Dale–Chall and SPACHE use per-token analysis as the original research intended.
• Consistent tokenization — letter and character counting that works correctly with Coleman–Liau and similar formulas.

English only. For multilingual support, consider textstat.

Readability formulas

Dale–Chall grade bands

LIX score interpretation

Text statistics

textly.syllable_count(text)                  # total syllables
textly.lexicon_count(text, removepunct=True)  # word count
textly.sentence_count(text)                   # sentence count
textly.char_count(text, ignore_spaces=True)   # character count
textly.letter_count(text, ignore_spaces=True) # alphabetic characters only
textly.polysyllabcount(text)                  # words with ≥3 syllables
textly.monosyllabcount(text)                  # words with 1 syllable

# Averages
textly.avg_sentence_length(text)
textly.avg_syllables_per_word(text)
textly.avg_character_per_word(text)
textly.avg_letter_per_word(text)
textly.avg_sentence_per_word(text)

# Difficult word analysis
textly.difficult_words(text)        # count
textly.difficult_words_list(text)   # list of tokens
textly.is_difficult_word("synapse") # True/False
textly.is_easy_word("dog")          # True/False

Configuration

Rounding

By default, scores are returned unrounded. You can control this globally or per call.

# Global: round all subsequent calls to 2 decimal places
textly.set_rounding(True, points=2)

# Per-call: overrides the global setting for this call only
textly.flesch_kincaid_grade(text, rounding=True, points=1)
textly.flesch_reading_ease(text, rounding=False)  # unrounded regardless of global

Apostrophe handling

# Default: False (preserves apostrophes in contractions like don't, it's)
textly.set_rm_apostrophe(True)  # strips all apostrophes with other punctuation

Set this once at the start of your script — it affects all subsequent calls.

Custom syllable dictionary

Override syllable counts for specialized vocabulary.

textly.add_word_to_dictionary("pterodactyl", 4)
textly.add_words_from_file_to_dictionary("my_terms.json")
textly.overwrite_dictionary("full_replacement.json")
textly.revert_dictionary_to_default()
textly.print_dictionary()

Dictionary files use this JSON format:

{
  "CUSTOM_SYLLABLE_DICT": {
    "pterodactyl": 4,
    "crispr": 2
  }
}

Limitations

• SMOG requires ~30 sentences for reliable results; fewer than 3 returns 0.0.
• Short text snippets produce unstable scores across most formulas.
• Novel jargon may need custom dictionary entries for accurate syllable counts.
• The regex fallback is approximate by nature (~91% agreement with CMUdict).
• English only.

Contributing

Found a bug or have an idea? Open an issue. Want to contribute code? Submit a pull request.

1. Fork the repo and create a branch.
2. Add tests for your changes.
3. Open a PR.

Changelog

See CHANGELOG.md for release history.

License

MIT