Text Insights

Time-box: 60–75 minutes
Milestone: turn arbitrary text into normalised words, frequency counts, a stable ranking, and a reading-time estimate.

Companion learning path: Python From First Principles. If Python or Git is not ready yet, use the free installation guide.

Start your own copy

On GitHub, select Use this template → Create a new repository, then clone your new repository and work in that copy. The starting red checks are intentional; your goal is to turn them green and complete the two human-review gates in MASTERY.md.

Rules to make explicit

• A word is one or more Unicode alphabetic characters.
• Capitalisation does not create a different word.
• Digits and punctuation separate words.
• Top words sort by descending count, then alphabetically when counts tie.
• Reading time rounds upward and empty text takes zero minutes.

Clear rules make the result predictable and the tests meaningful.

Start here

python3 -B -I tests/run_tests.py

The untouched starter has exactly four intentional test_todo_... failures. Complete tokenize, word_counts, top_words, and reading_minutes in text_insights.py. Reuse earlier functions instead of implementing the same normalisation four times.

A small loop using character.isalpha() is enough; no package or regular expression is required.

Acceptance checks

• "Water, WATER!" produces ['water', 'water'].
• Hyphens, digits, and punctuation separate alphabetic runs.
• Counts use a dictionary and empty text produces empty collections.
• Equal counts are ranked alphabetically.
• limit and words_per_minute reject booleans and invalid whole numbers.
• Reading time rounds up: 201 words at 200 words per minute takes 2 minutes.
• python3 -B -I tests/run_tests.py exits successfully.

Then complete MASTERY.md.

Get your automatic project grade

1. Create your own copy from this template.

2. Read MASTERY.md, then create an attempt branch:

   git switch -c attempt/my-project

3. Build the project and run the same check GitHub uses:

   python3 -B -I tests/run_tests.py

4. Commit and push the attempt branch:

   git add .
   git commit -m "Complete project attempt"
   git push -u origin attempt/my-project

GitHub Actions grades every pushed attempt automatically. PASS — NAILED IT means every required check passed. REVISE — KEEP BUILDING means the run shows what to fix before you push again. You do not need the KODE Ń VIBE owner to review or start anything; the template's main branch stays quiet on purpose.

The free grading guide explains the result and its limits.