Scaffold textkit: readability, slugify, and stats modules with pytest suite

Python reference example for Coverage Tracker's generating-coverage-reports
guide; reports coverage and radon complexity to the demo instance.

Author: tbjers

.github/workflows/coverage.yml

@@ -0,0 +1,27 @@
+name: coverage
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  id-token: write   # OIDC → Worker
+  checks: write     # PR Check Run
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - run: pip install -e ".[dev]"
+
+      - run: coverage run -m pytest && coverage lcov -o coverage.lcov
+
+      - run: radon cc -j textkit > radon.json
+
+      - uses: CoverageTracker/coverage-tracker/.github/actions/report@v0.2.0
+        with:
+          worker-url: https://demo.coveragetracker.dev

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.coverage
+coverage.lcov
+radon.json
+htmlcov/
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/
+venv/

README.md

@@ -0,0 +1,34 @@
+# example-python
+
+[![coverage badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fdemo.coveragetracker.dev%2Fapi%2Fbadge%2FCoverageTracker%2Fexample-python%2Fcoverage.json)](https://demo.coveragetracker.dev/CoverageTracker/example-python?metric=coverage)
+[![complexity badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fdemo.coveragetracker.dev%2Fapi%2Fbadge%2FCoverageTracker%2Fexample-python%2Fcomplexity.json)](https://demo.coveragetracker.dev/CoverageTracker/example-python?metric=complexity)
+
+A small, idiomatic Python text-analysis toolkit used as the Python reference
+example for [Coverage Tracker](https://coveragetracker.dev). It exists to
+give the Python row in the
+[coverage report generation guide](https://coveragetracker.dev/docs/generating-coverage-reports)
+a live, working reference, and to populate the
+[demo dashboard](https://demo.coveragetracker.dev) with real trend data.
+
+**This is a demo/marketing repo, not a test suite for Coverage Tracker
+itself.**
+
+## What's here
+
+- `textkit/` — readability scoring, slug generation, and word-frequency
+  helpers, each with real branching logic.
+- `tests/` — a [pytest](https://pytest.org) suite with a few deliberately
+  uncovered branches, so `branch_coverage < line_coverage` shows up on the
+  dashboard.
+- `.github/workflows/coverage.yml` — runs tests under
+  [coverage.py](https://coverage.readthedocs.io), generates a
+  [Radon](https://radon.readthedocs.io) complexity report, then reports both
+  to the demo instance via the `coverage-tracker` reporting Action.
+
+## Running locally
+
+```sh
+pip install -e ".[dev]"
+coverage run -m pytest && coverage lcov -o coverage.lcov   # writes coverage.lcov
+radon cc -j textkit > radon.json
+```

pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "textkit"
+version = "0.1.0"
+description = "Small text-analysis toolkit — Python reference example for Coverage Tracker."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "coverage>=7", "radon>=6"]
+
+[tool.setuptools]
+packages = ["textkit"]
+
+[tool.coverage.run]
+source = ["textkit"]
+branch = true
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

tests/test_readability.py

@@ -0,0 +1,43 @@
+import pytest
+
+from textkit.readability import count_syllables, flesch_kincaid_grade, grade_label
+
+
+def test_count_syllables_simple_word():
+    assert count_syllables("cat") == 1
+
+
+def test_count_syllables_silent_e_is_trimmed():
+    assert count_syllables("bike") == 1
+
+
+def test_count_syllables_le_ending_not_trimmed():
+    assert count_syllables("apple") == 2
+
+
+def test_count_syllables_blank_string():
+    assert count_syllables("   ") == 0
+
+
+def test_flesch_kincaid_grade_simple_text_scores_low():
+    grade = flesch_kincaid_grade("The cat sat on the mat. It was happy.")
+    assert grade < 5
+
+
+def test_flesch_kincaid_grade_raises_on_empty_text():
+    with pytest.raises(ValueError):
+        flesch_kincaid_grade("   ...   ")
+
+
+@pytest.mark.parametrize(
+    "grade,expected",
+    [
+        (2, "Elementary school"),
+        (7, "Middle school"),
+        (10, "High school"),
+        (14, "College"),
+        (20, "Graduate"),
+    ],
+)
+def test_grade_label_bands(grade, expected):
+    assert grade_label(grade) == expected

tests/test_slugify.py

@@ -0,0 +1,32 @@
+import pytest
+
+from textkit.slugify import is_slug, slugify
+
+
+def test_slugify_basic_text():
+    assert slugify("Hello, World!") == "hello-world"
+
+
+def test_slugify_collapses_repeated_separators():
+    assert slugify("  multiple   spaces--and--dashes  ") == "multiple-spaces-and-dashes"
+
+
+def test_slugify_strips_accents():
+    assert slugify("Café Münchën") == "cafe-munchen"
+
+
+def test_slugify_raises_when_nothing_sluggable():
+    with pytest.raises(ValueError):
+        slugify("!!!???")
+
+
+def test_is_slug_valid():
+    assert is_slug("hello-world") is True
+
+
+def test_is_slug_rejects_uppercase():
+    assert is_slug("Hello-World") is False
+
+
+def test_is_slug_empty_string():
+    assert is_slug("") is False

tests/test_stats.py

@@ -0,0 +1,34 @@
+import pytest
+
+from textkit.stats import most_common_word, tokenize, word_frequencies
+
+
+def test_tokenize_lowercases_and_strips_punctuation():
+    assert tokenize("Hello, World! It's great.") == ["hello", "world", "it's", "great"]
+
+
+def test_word_frequencies_excludes_default_stopwords():
+    text = "the cat and the dog and the cat"
+    assert word_frequencies(text, top_n=2) == [("cat", 2), ("dog", 1)]
+
+
+def test_word_frequencies_with_custom_stopwords():
+    result = word_frequencies("red green red blue", stopwords={"red"})
+    assert result == [("green", 1), ("blue", 1)]
+
+
+def test_word_frequencies_returns_empty_when_all_stopwords():
+    assert word_frequencies("the a an") == []
+
+
+def test_word_frequencies_raises_on_non_positive_top_n():
+    with pytest.raises(ValueError):
+        word_frequencies("hello world", top_n=0)
+
+
+def test_most_common_word_returns_top_word():
+    assert most_common_word("dog dog cat") == "dog"
+
+
+def test_most_common_word_returns_none_for_empty_result():
+    assert most_common_word("the a an") is None

textkit/__init__.py

@@ -0,0 +1,17 @@
+"""textkit — a small text-analysis toolkit.
+
+Readability scoring, slug generation, and word-frequency statistics.
+"""
+
+from textkit.readability import flesch_kincaid_grade, grade_label
+from textkit.slugify import is_slug, slugify
+from textkit.stats import most_common_word, word_frequencies
+
+__all__ = [
+    "flesch_kincaid_grade",
+    "grade_label",
+    "is_slug",
+    "slugify",
+    "most_common_word",
+    "word_frequencies",
+]

textkit/readability.py

@@ -0,0 +1,55 @@
+"""Flesch-Kincaid style readability scoring for plain text."""
+
+from __future__ import annotations
+
+import re
+
+
+def count_syllables(word: str) -> int:
+    """Rough heuristic syllable count for a single word."""
+    word = word.lower().strip()
+    if not word:
+        return 0
+
+    groups = re.findall(r"[aeiouy]+", word)
+    count = len(groups)
+
+    if word.endswith("e") and not word.endswith("le") and count > 1:
+        count -= 1
+
+    return max(count, 1)
+
+
+def flesch_kincaid_grade(text: str) -> float:
+    """Compute the Flesch-Kincaid grade level for `text`.
+
+    Raises ValueError if the text has no scorable sentences or words.
+    """
+    sentences = [s for s in re.split(r"[.!?]+", text) if s.strip()]
+    words = re.findall(r"[A-Za-z']+", text)
+
+    if not sentences or not words:
+        raise ValueError("text must contain at least one sentence and word")
+
+    syllables = sum(count_syllables(w) for w in words)
+
+    words_per_sentence = len(words) / len(sentences)
+    syllables_per_word = syllables / len(words)
+
+    grade = 0.39 * words_per_sentence + 11.8 * syllables_per_word - 15.59
+    return round(grade, 2)
+
+
+def grade_label(grade: float) -> str:
+    """Map a numeric grade level to a human-readable band."""
+    if grade < 0:
+        return "Below grade level"
+    if grade <= 5:
+        return "Elementary school"
+    if grade <= 8:
+        return "Middle school"
+    if grade <= 12:
+        return "High school"
+    if grade <= 16:
+        return "College"
+    return "Graduate"

textkit/slugify.py

@@ -0,0 +1,42 @@
+"""URL-safe slug generation."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str, max_length: int = 50) -> str:
+    """Convert `text` into a lowercase, hyphenated URL slug.
+
+    Truncates to `max_length` without cutting a word in half. Raises
+    ValueError if `max_length` isn't positive or the result would be empty.
+    """
+    if max_length <= 0:
+        raise ValueError("max_length must be positive")
+
+    normalized = unicodedata.normalize("NFKD", text)
+    ascii_text = normalized.encode("ascii", "ignore").decode("ascii")
+    slug = _NON_ALNUM.sub("-", ascii_text.lower()).strip("-")
+
+    if not slug:
+        raise ValueError("text has no sluggable characters")
+
+    if len(slug) <= max_length:
+        return slug
+
+    truncated = slug[:max_length]
+    last_hyphen = truncated.rfind("-")
+    if last_hyphen > 0:
+        truncated = truncated[:last_hyphen]
+
+    return truncated.strip("-")
+
+
+def is_slug(value: str) -> bool:
+    """Return True if `value` is already a valid slug."""
+    if not value:
+        return False
+    return bool(re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", value))