pyproject.toml and an installable package

import tomllib

# Add a [build-system] table for setuptools, requires-python = ">=3.10",
# and a [project.scripts] table with wordstat = "wordstat.cli:main".
PYPROJECT = """
[project]
name = "wordstat"
version = "0.1.0"
description = "Show the most common words in a text file"
"""

if __name__ == "__main__":
    data = tomllib.loads(PYPROJECT)
    print(data["project"]["name"], data["project"]["version"])
    print("scripts:", data["project"].get("scripts", {}))

import tomllib

import main


def load():
    try:
        return tomllib.loads(main.PYPROJECT)
    except tomllib.TOMLDecodeError as err:
        raise AssertionError(f"PYPROJECT is not valid TOML: {err}") from None


def test_build_system():
    """[build-system] names what to install and the backend to build with"""
    build = load().get("build-system")
    assert build is not None, "add a [build-system] table"
    assert build.get("requires"), "[build-system] needs requires, a list such as [\"setuptools >= 77.0.3\"]"
    assert build.get("build-backend") == "setuptools.build_meta", "for setuptools, build-backend is \"setuptools.build_meta\""


def test_name_and_version():
    """[project] has the name wordstat and a version"""
    project = load().get("project", {})
    assert project.get("name") == "wordstat", f"name is {project.get('name')!r}; it must be \"wordstat\""
    assert project.get("version"), "add a version, such as \"0.1.0\""


def test_requires_python():
    """requires-python declares the minimum Python, 3.10"""
    project = load().get("project", {})
    assert project.get("requires-python") == ">=3.10", f"requires-python is {project.get('requires-python')!r}; use \">=3.10\""


def test_console_script():
    """[project.scripts] maps the command wordstat to wordstat.cli:main"""
    scripts = load().get("project", {}).get("scripts", {})
    assert scripts.get("wordstat") == "wordstat.cli:main", f"[project.scripts] has {scripts}; add wordstat = \"wordstat.cli:main\""

import argparse
import sys
from pathlib import Path

from wordstat.core import top_words


def main(argv: list[str] | None = None) -> int:
    """Entry point of the wordstat command: wordstat = "wordstat.cli:main"."""
    parser = argparse.ArgumentParser(prog="wordstat", description="Show the most common words in a file.")
    parser.add_argument("path", help="the text file to read")
    # Add -n/--top (an int, default 3), and return 1 with a message on
    # stderr when the file does not exist.
    args = parser.parse_args(argv)
    text = Path(args.path).read_text(encoding="utf-8")
    for word, count in top_words(text):
        print(f"{count} {word}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

import contextlib
import io
import tempfile
from pathlib import Path

import main

TEXT = "The cat sat. The cat ran! The end."


def run(*args):
    out, err = io.StringIO(), io.StringIO()
    with tempfile.TemporaryDirectory() as tmp:
        path = Path(tmp, "story.txt")
        path.write_text(TEXT, encoding="utf-8")
        argv = [str(path) if arg == "FILE" else arg for arg in args]
        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
            status = main.main(argv)
    return status, out.getvalue(), err.getvalue()


def test_prints_top_three():
    """wordstat FILE prints the three most common words and returns 0"""
    status, out, _ = run("FILE")
    assert out == "3 the\n2 cat\n1 sat\n", f"printed {out!r}"
    assert status == 0, f"returned {status!r}; return 0 on success"


def test_top_option():
    """-n 1 and --top 2 choose how many words to print"""
    _, out, _ = run("-n", "1", "FILE")
    assert out == "3 the\n", f"with -n 1 printed {out!r}"
    _, out, _ = run("--top", "2", "FILE")
    assert out == "3 the\n2 cat\n", f"with --top 2 printed {out!r}"


def test_missing_file():
    """A missing file prints a message on stderr and returns 1"""
    try:
        status, out, err = run("no-such-file.txt")
    except FileNotFoundError:
        raise AssertionError("FileNotFoundError escaped main; catch it and return 1") from None
    assert status == 1, f"returned {status!r}; return 1 when the file is missing"
    assert "no-such-file.txt" in err, f"stderr was {err!r}; name the missing file there"
    assert out == "", f"stdout should stay empty, got {out!r}"

"""Show the most common words in a text."""

__version__ = "0.1.0"

from collections import Counter


def top_words(text: str, n: int = 3) -> list[tuple[str, int]]:
    """The n most common words, lowercased and without punctuation, most common first."""
    words = [word.strip(".,!?;:\"'()").lower() for word in text.split()]
    return Counter(word for word in words if word).most_common(n)

import unittest

from wordstat.core import top_words


class TestTopWords(unittest.TestCase):
    # Add one focused test per behaviour: case is ignored, punctuation is
    # stripped, and n limits how many words come back.
    def test_most_common_first(self) -> None:
        self.assertEqual(top_words("b a b", 2), [("b", 2), ("a", 1)])


if __name__ == "__main__":
    suite = unittest.TestLoader().loadTestsFromTestCase(TestTopWords)
    unittest.TextTestRunner(verbosity=2).run(suite)

import unittest
from collections import Counter

import main


def run_against(implementation):
    saved = main.top_words
    main.top_words = implementation
    try:
        result = unittest.TestResult()
        unittest.TestLoader().loadTestsFromTestCase(main.TestTopWords).run(result)
    finally:
        main.top_words = saved
    return result


def keeps_case(text, n=3):
    words = [word.strip(".,!?;:\"'()") for word in text.split()]
    return Counter(word for word in words if word).most_common(n)


def keeps_punctuation(text, n=3):
    return Counter(word.lower() for word in text.split()).most_common(n)


def ignores_n(text, n=3):
    words = [word.strip(".,!?;:\"'()").lower() for word in text.split()]
    return Counter(word for word in words if word).most_common()


BROKEN = {
    "case is not ignored": keeps_case,
    "punctuation is kept": keeps_punctuation,
    "n is ignored": ignores_n,
}


def test_correct_code_passes():
    """At least 4 tests, and all pass with the real top_words"""
    result = run_against(main.top_words)
    failing = [test.id() for test, _ in result.failures + result.errors]
    assert result.wasSuccessful(), f"these tests fail on correct code: {failing}"
    assert result.testsRun >= 4, f"{result.testsRun} tests ran; write at least 4 focused tests"


def test_every_bug_is_caught():
    """Each of three broken versions makes a test fail"""
    missed = [bug for bug, broken in BROKEN.items() if run_against(broken).wasSuccessful()]
    if missed:
        assert False, f"no test fails when {missed[0]}; add a test for it"

"""Show the most common words in a text."""

__version__ = "0.1.0"

from collections import Counter


def top_words(text: str, n: int = 3) -> list[tuple[str, int]]:
    """The n most common words, lowercased and without punctuation, most common first."""
    words = [word.strip(".,!?;:\"'()").lower() for word in text.split()]
    return Counter(word for word in words if word).most_common(n)