Hands-on lab — Day 45: Strings and Text Processing

the river and the reader
A river starts as a thin trickle high in the cold mountains.
That river grows stronger as water joins it from smaller streams.
Every river carries silt and boats and quiet stories toward the sea.
People gather near a river because a river always means life.
In spring a river swells, and in summer a river runs low and clear.
A patient reader can follow a river from its source to its mouth.
Text is a river too: words flow, words join, words split, words merge.
Learn to shape that flow and no river of words will ever drown you.

#!/usr/bin/env python3
"""Build a Text Report -- Day 045 lab (completed reference implementation).

Reads examples/sample.txt and prints a clean, aligned report built entirely
from string methods and f-strings:

  * a title-cased heading taken from the first line,
  * line, word, character, and unique-word counts,
  * the most common word (found with split + a plain dict),
  * a formatted statistics table using f-string format specs,
  * small demonstrations of slicing and strip/split/join.

It reads only the local sample file next to this script. No network, no
arguments, no writing outside standard output.
"""

from pathlib import Path

# Characters we peel off the edges of a word before counting it. Using
# str.strip keeps this beginner-friendly; a complex pattern would call for
# the regular-expression tools introduced on Day 38.
PUNCTUATION = ".,;:!?\"'()[]-"

REPORT_WIDTH = 44
LABEL_WIDTH = 20
VALUE_WIDTH = 10


def load_text(path):
    """Return the full contents of a UTF-8 text file as one str."""
    return Path(path).read_text(encoding="utf-8")


def normalize(token):
    """Lower-case a token and strip surrounding punctuation.

    "River," -> "river"; "words." -> "words"; "too:" -> "too".
    """
    return token.strip(PUNCTUATION).lower()


def count_words(text):
    """Return a dict mapping each normalized word to how often it appears."""
    counts = {}
    for token in text.split():
        word = normalize(token)
        if word:  # skip tokens that were pure punctuation
            counts[word] = counts.get(word, 0) + 1
    return counts


def most_common(counts):
    """Return (word, n) for the most frequent word; ties break on first seen."""
    best_word = ""
    best_n = 0
    for word, n in counts.items():
        if n > best_n:
            best_word, best_n = word, n
    return best_word, best_n


def main():
    sample_path = Path(__file__).resolve().parent / "sample.txt"
    text = load_text(sample_path)

    lines = text.splitlines()
    heading = lines[0].strip().title()

    words = text.split()
    counts = count_words(text)
    common_word, common_n = most_common(counts)

    n_lines = len(lines)
    n_words = len(words)
    n_chars = len(text)
    n_unique = len(counts)

    bar = "=" * REPORT_WIDTH
    print(bar)
    print(f"{heading:^{REPORT_WIDTH}}")
    print(bar)
    print()

    # Slicing + strip/split/join in one line: collapse all whitespace, then
    # take the first 40 characters as a preview.
    preview = " ".join(text.split())[:40]
    print(f"Preview:  {preview}...")
    print(f"Heading reversed:  {heading[::-1]}")
    print(f"First / last body word:  {words[1]!r} / {words[-1].strip(PUNCTUATION)!r}")
    print()

    print(f"{'Statistic':<{LABEL_WIDTH}}{'Value':>{VALUE_WIDTH}}")
    print("-" * (LABEL_WIDTH + VALUE_WIDTH))
    print(f"{'Lines':<{LABEL_WIDTH}}{n_lines:>{VALUE_WIDTH}}")
    print(f"{'Words':<{LABEL_WIDTH}}{n_words:>{VALUE_WIDTH}}")
    print(f"{'Characters':<{LABEL_WIDTH}}{n_chars:>{VALUE_WIDTH}}")
    print(f"{'Unique words':<{LABEL_WIDTH}}{n_unique:>{VALUE_WIDTH}}")
    print()

    pct = common_n / n_words * 100
    print(f'Most common word:  "{common_word}" ({common_n} times, {pct:.1f}% of words)')


if __name__ == "__main__":
    main()

lesson_id: D045
day: 45
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-045-strings-and-text-processing
run_commands:
  - python3 examples/text_report.py
  - python3 starter/text_report.py
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- starter/text_report.py  # optional: reset your work'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS, Python 3.14.0, bash tests/run_tests.sh → 9 checks, 0 failure(s).'

# Dependencies — Day 045 lab

**Only Python 3 and a POSIX shell.** This lab installs nothing:

- `python3` (version 3.8 or newer — any modern install works; captured on
  3.14). Check with `python3 --version`.
- `bash` (for the test runner — preinstalled on macOS and Linux).

The program uses only the Python standard library (`pathlib`), which ships
with Python itself. There is deliberately no `requirements.txt`: string and
text processing are core language features, so no third-party package is
needed.

**Windows:** run the commands inside WSL (Windows Subsystem for Linux) so the
`bash tests/run_tests.sh` step works, or run the Python program directly with
`python examples\text_report.py` in PowerShell and check the numbers against
`expected-output/FIELDS.md` by hand.

# Strings worksheet — Day 045

Fill this in as you complete the lab. Everything you need comes from running
`python3 examples/text_report.py` and experimenting in a Python shell
(`python3`), using only string methods and f-strings.

## 1. Word count of the sample

Run the completed report (or your finished starter) and record the total word
count it prints:

- Words in `examples/sample.txt`: **______**

## 2. One slice result

Pick any string from the sample (for example the title-cased heading
`The River And The Reader`) and write a slice expression plus its result. Try
it in the shell first: `python3 -c "print('The River And The Reader'[4:9])"`.

- Slice expression I used: `______________________`
- Result it produced: `______________________`

## 3. An f-string you wrote

Write one f-string of your own that embeds at least one expression and one
format spec (for example `:>10` to right-align a number, or `:.1f` for one
decimal place). Show the f-string and the line it prints.

- My f-string: `f"______________________"`
- What it printed: `______________________`

## Notes

Anything that surprised you (an off-by-one in a slice, a method that returned a
new string instead of changing the original, a quoting problem inside an
f-string) — jot it here so you remember it next time.

#!/usr/bin/env python3
"""Build a Text Report -- Day 045 lab STARTER.

Complete the five numbered exercises below, then run your program:

    python3 starter/text_report.py

Check your work with:

    bash tests/run_tests.sh

The finished reference lives in examples/text_report.py -- read it only after
you have tried each exercise yourself. Edit ONLY the lines the exercises point
to; leave the rest of the scaffolding in place.
"""

from pathlib import Path

# Characters we peel off the edges of a word before counting it.
PUNCTUATION = ".,;:!?\"'()[]-"

REPORT_WIDTH = 44
LABEL_WIDTH = 20
VALUE_WIDTH = 10


def normalize(token):
    """Lower-case a token and strip surrounding punctuation: 'River,' -> 'river'."""
    return token.strip(PUNCTUATION).lower()


def main():
    sample_path = Path(__file__).resolve().parent.parent / "examples" / "sample.txt"

    # Exercise 1: read the whole file into `text` as one UTF-8 string.
    #   Replace None with:  sample_path.read_text(encoding="utf-8")
    text = None
    if text is None:
        print("Exercise 1 not done yet: read the sample file into `text`.")
        return

    lines = text.splitlines()
    words = text.split()

    # Exercise 2: build a title-cased heading from the first line.
    #   Use lines[0].strip().title()   (str methods, chained left to right)
    heading = "HEADING GOES HERE"

    # Exercise 3: count words into a dict using split + normalize.
    #   For each token in `words`: word = normalize(token); if word is not empty,
    #   add 1 to counts[word] (start each new word at 0 with counts.get).
    counts = {}
    # ... write the counting loop here ...

    # Exercise 4: find the most common word and how many times it appears.
    #   Loop over counts.items() and keep the (word, n) with the largest n.
    common_word, common_n = "", 0
    # ... write the loop here ...

    n_lines = len(lines)
    n_words = len(words)
    n_chars = len(text)
    n_unique = len(counts)

    bar = "=" * REPORT_WIDTH
    print(bar)
    print(f"{heading:^{REPORT_WIDTH}}")
    print(bar)
    print()

    # Exercise 5: print the four statistic rows using f-string format specs so
    #   the label is left-aligned in LABEL_WIDTH and the number right-aligned in
    #   VALUE_WIDTH. The 'Lines' row is done for you; add 'Words', 'Characters',
    #   and 'Unique words' the same way.
    print(f"{'Statistic':<{LABEL_WIDTH}}{'Value':>{VALUE_WIDTH}}")
    print("-" * (LABEL_WIDTH + VALUE_WIDTH))
    print(f"{'Lines':<{LABEL_WIDTH}}{n_lines:>{VALUE_WIDTH}}")
    # ... add the Words, Characters, and Unique words rows here ...

    print()
    if n_words:
        pct = common_n / n_words * 100
        print(f'Most common word:  "{common_word}" ({common_n} times, {pct:.1f}% of words)')


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
# Tests for the Day 045 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Runs the completed reference program on the committed sample and checks the
# exact counts and formatted lines it must produce, then confirms a couple of
# slicing/method facts directly with python3. No network is used.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

grep_check() {
  local label="$1" pattern="$2" text="$3"
  if printf '%s\n' "${text}" | grep -Eq "${pattern}"; then
    check "${label}" "yes"
  else
    check "${label}" "no"
  fi
}

echo "Running examples/text_report.py ..."
if ! output="$(python3 "${lab_dir}/examples/text_report.py" 2>&1)"; then
  check "reference program exits successfully" "no"
  printf '%s\n' "${output}" | sed 's/^/    /'
else
  check "reference program exits successfully" "yes"
  grep_check "title-cased heading present"      '^ *The River And The Reader *$'                 "${output}"
  grep_check "Lines count is 9"                  '^Lines +9$'                                     "${output}"
  grep_check "Words count is 105"               '^Words +105$'                                    "${output}"
  grep_check "Characters count is 556"          '^Characters +556$'                               "${output}"
  grep_check "Unique words count is 66"         '^Unique words +66$'                              "${output}"
  grep_check "most common word is river (11)"   'Most common word:  "river" \(11 times, 10\.5% of words\)' "${output}"
fi

echo "Checking slicing and string-method facts with python3 ..."
if python3 - <<'PY'
# Slicing: negative index, reverse, and a range slice.
h = "The River And The Reader"
assert h[0] == "T", "s[0] should be the first character"
assert h[-1] == "r", "s[-1] should be the last character"
assert h[4:9] == "River", "s[4:9] should slice out 'River'"
assert h[::-1] == "redaeR ehT dnA reviR ehT", "s[::-1] should reverse the string"
# Methods produce NEW strings; the original is unchanged (immutability).
assert "River,".strip(".,") == "River"
assert "  hi  ".strip() == "hi"
assert "a,b,c".split(",") == ["a", "b", "c"]
assert "-".join(["a", "b", "c"]) == "a-b-c"
assert "Hello".lower() == "hello" and "Hello".upper() == "HELLO"
assert "banana".count("a") == 3
assert f"{3.14159:.2f}" == "3.14"
assert f"{42:>5}" == "   42"
PY
then
  check "slicing/method assertions all hold" "yes"
else
  check "slicing/method assertions all hold" "no"
fi

echo "Checking the starter is present and runnable ..."
if python3 "${lab_dir}/starter/text_report.py" >/dev/null 2>&1; then
  check "starter program runs without crashing" "yes"
else
  check "starter program runs without crashing" "no"
fi
if grep -q 'text = None' "${lab_dir}/starter/text_report.py"; then
  echo "Note: starter/text_report.py still has unfinished exercises (that is expected before you complete them)."
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]