diff --git a/README.md b/README.md index 3effca8..7e5962e 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,14 @@ Each lecture has its own screenshot in `docs/images/` (made by `docs/images/capt ![Lecture 2: Hello, World! in the browser](docs/images/lecture-02.png) +**Lecture 3: the command line.** `pwd`, `ls`, `cd`, `mkdir`, `touch` and `rm` (with `rm -rf` as the command to double-check). `flask_day_54.domain.cli_basics` lists them with their Windows equivalents: `python -m flask_day_54.domain.cli_basics`. The screenshot shows the real commands run in a temporary folder. + +![Lecture 3: the command line](docs/images/lecture-03.png) + +**Lecture 4: `__name__` and `__main__`.** A file run directly has `__name__ == "__main__"`; an imported file has its module name. `app.run()` sits under that check in `hello.py`, so there are two ways to start the server: `flask --app flask_day_54.presentation.hello run` or `python -m flask_day_54.presentation.hello`. Try `python -m flask_day_54.domain.name_demo`. + +![Lecture 4: __name__ and __main__](docs/images/lecture-04.png) + ## 📋 Requirements - Python 3.13 or newer, because the project sets `requires-python = ">=3.13"` in `pyproject.toml`. diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index e4857fb..4235e9a 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -18,7 +18,7 @@ document of a type. `Primary File` may contain a glob (e.g. | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 | | DICT | Domain Dictionary | docs/dictionary.md | 002 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 017 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 018 | ## Languages diff --git a/docs/images/capture.py b/docs/images/capture.py index 9d27ca8..b49f322 100644 --- a/docs/images/capture.py +++ b/docs/images/capture.py @@ -1,214 +1,229 @@ -"""Create the lecture screenshots in docs/images/ without touching the desktop. - -Every screenshot is taken by a headless Edge or Chrome (no window, no mouse, no -keyboard). Terminal screenshots render the real output of real commands. - -Usage (from the repository root, with the project's .venv active): - python docs/images/capture.py 1 2 3 4 5 6 -""" -# Developer tool only (not shipped in the package): every command it runs is a fixed list -# built from constants, sys.executable and local paths; it reads no external input. - -import html -import os -import shutil -import subprocess -import sys -import tempfile -import time -import urllib.request -from pathlib import Path - -ROOT = Path(__file__).resolve().parents[2] -OUT = ROOT / "docs" / "images" -SOURCES = OUT / "sources" -BROWSERS = [ - r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe", - r"C:\Program Files\Google\Chrome\Application\chrome.exe", - "microsoft-edge", - "google-chrome", - "chromium", -] -PORT = 5057 -APP = "flask_day_54.presentation.hello" - -TERMINAL_CSS = """ -body{margin:0;background:#1e1e1e;font-family:Consolas,'DejaVu Sans Mono',monospace;color:#d4d4d4} -.bar{background:#333;color:#ccc;padding:8px 14px;font-size:14px} -pre{margin:0;padding:16px 18px;font-size:15px;line-height:1.45;white-space:pre-wrap} -.p{color:#6a9955}.c{color:#9cdcfe} -""" - -BROWSER_CSS = """ -body{margin:0;background:#f3f3f3;font-family:Segoe UI,Arial,sans-serif} -.tab{background:#dde3ea;padding:8px 14px;font-size:13px;color:#333} -.url{background:#fff;margin:8px;padding:6px 12px;border:1px solid #bbb;border-radius:14px;font-size:14px} -.page{background:#fff;height:150px;padding:16px;font-size:16px;font-family:Times New Roman,serif} -""" - - -def find_browser() -> str: - for candidate in BROWSERS: - found = shutil.which(candidate) or (candidate if os.path.exists(candidate) else None) - if found: - return found - raise SystemExit("No Edge or Chrome found for headless screenshots") - - -def shot(page: Path, png: Path, width: int, height: int) -> None: - """Take a headless screenshot of a local page or a URL.""" - target = page.as_uri() if isinstance(page, Path) else page - profile = tempfile.mkdtemp(prefix="shot-") - subprocess.run( # nosemgrep - [ - find_browser(), - "--headless=new", - "--disable-gpu", - "--hide-scrollbars", - f"--user-data-dir={profile}", - f"--window-size={width},{height}", - f"--screenshot={png}", - "--virtual-time-budget=3000", - target, - ], - check=True, - capture_output=True, - timeout=60, - ) - shutil.rmtree(profile, ignore_errors=True) - print("wrote", png.relative_to(ROOT)) - - -def run(cmd: list[str], cwd: Path, timeout: int = 30) -> str: - done = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout) # nosemgrep - return (done.stdout + done.stderr).rstrip("\n") - - -def terminal_page(title: str, entries: list[tuple[str, str]], png: Path, height: int) -> None: - """Render (command, output) pairs as a terminal and take the screenshot.""" - lines = [] - for command, output in entries: - lines.append(f'$ {html.escape(command)}') - if output: - lines.append(html.escape(output)) - page = ( - f"" - f"
{html.escape(title)}
" + "\n".join(lines) + "
" - ) - SOURCES.mkdir(exist_ok=True) - src = SOURCES / (png.stem + ".html") - src.write_text(page, encoding="utf-8") - shot(src, png, 900, height) - - -def python() -> str: - return sys.executable - - -def step1() -> None: - shot(SOURCES / "lecture-01.html", OUT / "lecture-01.png", 900, 400) - - -def start_server() -> subprocess.Popen: - proc = subprocess.Popen( # nosemgrep - [python(), "-m", "flask", "--app", APP, "run", "--port", str(PORT)], - cwd=ROOT, - stdout=subprocess.PIPE, - stderr=subprocess.STDOUT, - text=True, - ) - for _ in range(40): - try: - urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=1).read() - return proc - except OSError: - time.sleep(0.25) # nosemgrep - proc.kill() - raise SystemExit("server did not start") - - -def step2() -> None: - proc = start_server() - try: - body = urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=3).read().decode() - page = ( - f"" - f"
127.0.0.1:5057
" - f"
http://127.0.0.1:{PORT}/
" - f"
{body}
" - ) - src = SOURCES / "lecture-02.html" - src.write_text(page, encoding="utf-8") - shot(src, OUT / "lecture-02.png", 700, 230) - finally: - proc.kill() - - -def step3() -> None: - work = Path(tempfile.mkdtemp(prefix="cli-demo-")) - bash = shutil.which("bash") or "bash" - entries = [] - script = [ - "pwd", - "ls", - "mkdir my_project", - "cd my_project && touch hello.py && ls", - "cd .. && rm -rf my_project && ls", - ] - for command in script: - output = run([bash, "-c", command], work) - entries.append((command, output.replace(str(work).replace("\\", "/"), "~/demo"))) - shutil.rmtree(work, ignore_errors=True) - terminal_page("Terminal - lecture 3: the command line", entries, OUT / "lecture-03.png", 330) - - -def step4() -> None: - entries = [] - cmd = "python -m flask_day_54.domain.name_demo" - entries.append((cmd, run([python(), "-m", "flask_day_54.domain.name_demo"], ROOT))) - imp = "python -c \"import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))\"" - entries.append( - ( - imp, - run( - [ - python(), - "-c", - "import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))", - ], - ROOT, - ), - ) - ) - server = subprocess.Popen( # nosemgrep - [python(), "-m", "flask_day_54.presentation.hello"], - cwd=ROOT, - stdout=subprocess.PIPE, - stderr=subprocess.STDOUT, - text=True, - ) - time.sleep(3) # nosemgrep - server.kill() - out = (server.stdout.read() if server.stdout else "").strip() - entries.append(("python -m flask_day_54.presentation.hello", out + "\n^C")) - terminal_page("Terminal - lecture 4: __name__ and __main__", entries, OUT / "lecture-04.png", 560) - - -def step5() -> None: - module = "flask_day_54.domain.first_class_functions" - entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))] - terminal_page("Terminal - lecture 5: functions as first-class objects", entries, OUT / "lecture-05.png", 420) - - -def step6() -> None: - module = "flask_day_54.domain.decorators" - entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))] - terminal_page("Terminal - lecture 6: decorators and the @ syntax", entries, OUT / "lecture-06.png", 380) - - -STEPS = {1: step1, 2: step2, 3: step3, 4: step4, 5: step5, 6: step6} - -if __name__ == "__main__": - os.environ["PYTHONPATH"] = str(ROOT / "src") - for number in [int(a) for a in sys.argv[1:]] or STEPS: - STEPS[number]() +"""Create the lecture screenshots in docs/images/ without touching the desktop. + +Every screenshot is taken by a headless Edge or Chrome (no window, no mouse, no +keyboard). Terminal screenshots render the real output of real commands. + +Usage (from the repository root, with the project's .venv active): + python docs/images/capture.py 1 2 3 4 5 6 +""" +# Developer tool only (not shipped in the package): every command it runs is a fixed list +# built from constants, sys.executable and local paths; it reads no external input. + +import html +import os +import re +import shutil +import subprocess +import sys +import tempfile +import time +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +OUT = ROOT / "docs" / "images" +SOURCES = OUT / "sources" +BROWSERS = [ + r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe", + r"C:\Program Files\Google\Chrome\Application\chrome.exe", + "microsoft-edge", + "google-chrome", + "chromium", +] +PORT = 5057 +APP = "flask_day_54.presentation.hello" + +TERMINAL_CSS = """ +body{margin:0;background:#1e1e1e;font-family:Consolas,'DejaVu Sans Mono',monospace;color:#d4d4d4} +.bar{background:#333;color:#ccc;padding:8px 14px;font-size:14px} +pre{margin:0;padding:16px 18px;font-size:15px;line-height:1.45;white-space:pre-wrap} +.p{color:#6a9955}.c{color:#9cdcfe} +""" + +BROWSER_CSS = """ +body{margin:0;background:#f3f3f3;font-family:Segoe UI,Arial,sans-serif} +.tab{background:#dde3ea;padding:8px 14px;font-size:13px;color:#333} +.url{background:#fff;margin:8px;padding:6px 12px;border:1px solid #bbb;border-radius:14px;font-size:14px} +.page{background:#fff;height:150px;padding:16px;font-size:16px;font-family:Times New Roman,serif} +""" + + +def find_browser() -> str: + for candidate in BROWSERS: + found = shutil.which(candidate) or (candidate if os.path.exists(candidate) else None) + if found: + return found + raise SystemExit("No Edge or Chrome found for headless screenshots") + + +def shot(page: Path, png: Path, width: int, height: int) -> None: + """Take a headless screenshot of a local page or a URL.""" + target = page.as_uri() if isinstance(page, Path) else page + profile = tempfile.mkdtemp(prefix="shot-") + subprocess.run( # nosemgrep + [ + find_browser(), + "--headless=new", + "--disable-gpu", + "--hide-scrollbars", + f"--user-data-dir={profile}", + f"--window-size={width},{height}", + f"--screenshot={png}", + "--virtual-time-budget=3000", + target, + ], + check=True, + capture_output=True, + timeout=60, + ) + shutil.rmtree(profile, ignore_errors=True) + print("wrote", png.relative_to(ROOT)) + + +def run(cmd: list[str], cwd: Path, timeout: int = 30) -> str: + done = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout) # nosemgrep + return (done.stdout + done.stderr).rstrip("\n") + + +def terminal_page(title: str, entries: list[tuple[str, str]], png: Path, height: int) -> None: + """Render (command, output) pairs as a terminal and take the screenshot.""" + lines = [] + for command, output in entries: + lines.append(f'$ {html.escape(command)}') + if output: + lines.append(html.escape(output)) + page = ( + f"" + f"
{html.escape(title)}
" + "\n".join(lines) + "
" + ) + SOURCES.mkdir(exist_ok=True) + src = SOURCES / (png.stem + ".html") + src.write_text(page, encoding="utf-8") + shot(src, png, 900, height) + + +def stop(proc: subprocess.Popen) -> None: + """Stop a server and its reloader child.""" + if os.name == "nt": + subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], capture_output=True) # nosemgrep + else: + proc.kill() + proc.wait(timeout=10) + + +def python() -> str: + return sys.executable + + +def step1() -> None: + shot(SOURCES / "lecture-01.html", OUT / "lecture-01.png", 900, 400) + + +def start_server() -> subprocess.Popen: + proc = subprocess.Popen( # nosemgrep + [python(), "-m", "flask", "--app", APP, "run", "--port", str(PORT)], + cwd=ROOT, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + for _ in range(40): + try: + urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=1).read() + return proc + except OSError: + time.sleep(0.25) # nosemgrep + proc.kill() + raise SystemExit("server did not start") + + +def step2() -> None: + proc = start_server() + try: + body = urllib.request.urlopen(f"http://127.0.0.1:{PORT}/", timeout=3).read().decode() + page = ( + f"" + f"
127.0.0.1:5057
" + f"
http://127.0.0.1:{PORT}/
" + f"
{body}
" + ) + src = SOURCES / "lecture-02.html" + src.write_text(page, encoding="utf-8") + shot(src, OUT / "lecture-02.png", 700, 230) + finally: + stop(proc) + + +def step3() -> None: + work = Path(tempfile.mkdtemp(prefix="cli-demo-")) + bash = shutil.which("bash") or "bash" + entries = [] + script = [ + "pwd", + "ls", + "mkdir my_project", + "cd my_project && touch hello.py && ls", + "rm -rf my_project && ls", + ] + for command in script: + output = run([bash, "-c", command], work) + entries.append((command, re.sub(r"/tmp/cli-demo-\w+", "~/demo", output))) + shutil.rmtree(work, ignore_errors=True) + terminal_page("Terminal - lecture 3: the command line", entries, OUT / "lecture-03.png", 330) + + +def step4() -> None: + entries = [] + cmd = "python -m flask_day_54.domain.name_demo" + entries.append((cmd, run([python(), "-m", "flask_day_54.domain.name_demo"], ROOT))) + imp = "python -c \"import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))\"" + entries.append( + ( + imp, + run( + [ + python(), + "-c", + "import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))", + ], + ROOT, + ), + ) + ) + server = subprocess.Popen( # nosemgrep + [python(), "-m", "flask_day_54.presentation.hello"], + cwd=ROOT, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + time.sleep(3) # nosemgrep + stop(server) + raw = (server.stdout.read() if server.stdout else "").strip() + # Leave out the .env tip and the random debugger PIN; they say nothing about the lecture. + kept = [ + line for line in raw.splitlines() if "Tip:" not in line and "Debugger PIN" not in line + ] + out = "\n".join(kept) + entries.append(("python -m flask_day_54.presentation.hello", out + "\n^C")) + terminal_page("Terminal - lecture 4: __name__ and __main__", entries, OUT / "lecture-04.png", 560) + + +def step5() -> None: + module = "flask_day_54.domain.first_class_functions" + entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))] + terminal_page("Terminal - lecture 5: functions as first-class objects", entries, OUT / "lecture-05.png", 420) + + +def step6() -> None: + module = "flask_day_54.domain.decorators" + entries = [(f"python -m {module}", run([python(), "-m", module], ROOT))] + terminal_page("Terminal - lecture 6: decorators and the @ syntax", entries, OUT / "lecture-06.png", 380) + + +STEPS = {1: step1, 2: step2, 3: step3, 4: step4, 5: step5, 6: step6} + +if __name__ == "__main__": + os.environ["PYTHONPATH"] = str(ROOT / "src") + for number in [int(a) for a in sys.argv[1:]] or STEPS: + STEPS[number]() diff --git a/docs/images/lecture-03.png b/docs/images/lecture-03.png new file mode 100644 index 0000000..a6be2a5 Binary files /dev/null and b/docs/images/lecture-03.png differ diff --git a/docs/images/lecture-04.png b/docs/images/lecture-04.png new file mode 100644 index 0000000..010b49c Binary files /dev/null and b/docs/images/lecture-04.png differ diff --git a/docs/images/sources/lecture-03.html b/docs/images/sources/lecture-03.html new file mode 100644 index 0000000..8260daa --- /dev/null +++ b/docs/images/sources/lecture-03.html @@ -0,0 +1,12 @@ +
Terminal - lecture 3: the command line
$ pwd
+~/demo
+$ ls
+$ mkdir my_project
+$ cd my_project && touch hello.py && ls
+hello.py
+$ rm -rf my_project && ls
\ No newline at end of file diff --git a/docs/images/sources/lecture-04.html b/docs/images/sources/lecture-04.html new file mode 100644 index 0000000..4df7a9c --- /dev/null +++ b/docs/images/sources/lecture-04.html @@ -0,0 +1,18 @@ +
Terminal - lecture 4: __name__ and __main__
$ python -m flask_day_54.domain.name_demo
+Running as the main program: the file was executed directly
+$ python -c "import flask_day_54.domain.name_demo as m; print(m.describe_name(m.__name__))"
+Running as an imported module named flask_day_54.domain.name_demo
+$ python -m flask_day_54.presentation.hello
+ * Serving Flask app 'hello'
+ * Debug mode: on
+WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
+ * Running on http://127.0.0.1:5000
+Press CTRL+C to quit
+ * Restarting with stat
+ * Debugger is active!
+^C
\ No newline at end of file diff --git a/docs/sqa/reviews/rc-017-code-mil-003-cli-and-main.md b/docs/sqa/reviews/rc-017-code-mil-003-cli-and-main.md new file mode 100644 index 0000000..133ec1b --- /dev/null +++ b/docs/sqa/reviews/rc-017-code-mil-003-cli-and-main.md @@ -0,0 +1,62 @@ +# Review of MIL-003 + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-017 | +| CrossReference | [MIL-003], [QC-PY-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-11-06 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [f8a1794] | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-003] +- Checklist used: [QC-PY-001] +- Scope: full review of the source and tests delivered by MIL-003 (src/, tests/) +- Language and domain: n/a +- Language reviewer: none (the reviewer reads English and knows the IT domain) +- Mode: autonomous, not independent (AI as stand-in for S01) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | Modules, functions and constants use snake_case / UPPER_SNAKE; classes none or PascalCase. | +| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names follow the lecture and the domain dictionary. | +| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff format` leaves files unchanged and `ruff check` (E, F, I, B, UP) passes; configured in pyproject.toml. | +| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every function signature is annotated, including `-> None`. | +| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No bare except and no swallowed exception. | +| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; no builtin shadowed. | +| 7 | Files, locks and connections are managed with context managers | N-A | No file, lock or connection is opened. | +| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Module and public names carry docstrings plus Doxygen comments. | +| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | N-A | Console output of the demo entry points (print under the __main__ guard) is the program's result, not diagnostic logging; no secrets handled. | +| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | No DCD exists in this project; the layered layout is recorded in ADR-0001. | +| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | pytest tests named for behaviour; no order or network dependence. | +| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | N-A | No type checker is configured (optional criterion). | +| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | Dependencies are declared in pyproject.toml; none unused (Flask is the optional `web` extra). | +| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Each constant is defined once in the constants.py of its layer. | +| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `domain` imports no framework or outer layer; imports point inward; no cycles. | +| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Small modules with one reason to change; no type tests or subclass hierarchies. | +| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | Layers domain, application, infrastructure, presentation under src/flask_day_54; tests in unit and e2e (ADR-0001); no layer merged. | +| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | English snake_case file names without spaces. | + +## Overall Verdict + +Go — All applicable mandatory criteria pass. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | S01 | - | + +--- + +[MIL-003]: ../../milestones/mil-003-cli-and-main.md +[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md +[f8a1794]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/054-flask/commit/f8a1794373b21d718d756215eae34c67e873fbd2 diff --git a/src/flask_day_54/domain/cli_basics.py b/src/flask_day_54/domain/cli_basics.py new file mode 100644 index 0000000..b223472 --- /dev/null +++ b/src/flask_day_54/domain/cli_basics.py @@ -0,0 +1,66 @@ +## @file cli_basics.py +# @brief Lecture 3 command line cheat sheet. +"""Command line cheat sheet with Windows equivalents.""" + +from dataclasses import dataclass + +from flask_day_54.domain.constants import CLI_COMMANDS + + +## @brief One command of the cheat sheet. +@dataclass(frozen=True, slots=True) +class CommandInfo: + """A shell command, its purpose, Windows equivalent and risk.""" + + name: str + purpose: str + windows_equivalent: str + is_destructive: bool + warning: str + + +def _all_commands() -> tuple[CommandInfo, ...]: + return tuple(CommandInfo(*row) for row in CLI_COMMANDS) + + +## @brief Look up one command by name. +# @param name Command name such as "ls" or "rm -rf". +# @return The command information. +# @throws ValueError When the command is not in the cheat sheet. +def describe_command(name: str) -> CommandInfo: + """Return the cheat sheet entry for a command name.""" + for command in _all_commands(): + if command.name == name: + return command + raise ValueError(f"Unknown command: {name!r}") + + +## @brief List the commands that remove data without asking. +def destructive_commands() -> tuple[CommandInfo, ...]: + """Return the destructive commands.""" + return tuple(c for c in _all_commands() if c.is_destructive) + + +## @brief Format the cheat sheet as text, one command per line. +def format_cheat_sheet() -> str: + """Return the cheat sheet as multi-line text.""" + lines: list[str] = [] + for command in _all_commands(): + line = ( + f"{command.name:<8} {command.purpose} " + f"(Windows: {command.windows_equivalent})" + ) + if command.is_destructive: + line += f" WARNING: {command.warning}" + lines.append(line) + return "\n".join(lines) + + +## @brief Print the cheat sheet. +def main() -> None: + """Print the cheat sheet; the output is the lecture's result.""" + print(format_cheat_sheet()) + + +if __name__ == "__main__": + main() diff --git a/src/flask_day_54/domain/constants.py b/src/flask_day_54/domain/constants.py index fdaae9a..2756463 100644 --- a/src/flask_day_54/domain/constants.py +++ b/src/flask_day_54/domain/constants.py @@ -6,3 +6,35 @@ from typing import Final ## @brief The greeting shown by the first Flask route. GREETING: Final[str] = "Hello, World!" + +## @brief Value of `__name__` when a file is executed directly. +MAIN_MODULE_NAME: Final[str] = "__main__" + +## @brief Sentence shown when the file runs as the main program. +MAIN_PROGRAM_SENTENCE: Final[str] = ( + "Running as the main program: the file was executed directly" +) + +## @brief Sentence template shown when the file is imported; `{name}` is the module. +IMPORTED_MODULE_SENTENCE: Final[str] = "Running as an imported module named {name}" + +## @brief Warning shown for commands that remove data without asking. +NO_CONFIRMATION_WARNING: Final[str] = "No confirmation is asked - double-check the path" + +## @brief Command line cheat sheet rows. +# Each row is (name, purpose, Windows equivalent, is destructive, warning). +CLI_COMMANDS: Final[tuple[tuple[str, str, str, bool, str], ...]] = ( + ("pwd", "Print the current working directory", "cd", False, ""), + ("ls", "List the files in a directory", "dir", False, ""), + ("cd", "Change the current directory", "cd", False, ""), + ("mkdir", "Create a new directory", "mkdir", False, ""), + ("touch", "Create an empty file", "type nul > file", False, ""), + ("rm", "Remove a file", "del file", True, NO_CONFIRMATION_WARNING), + ( + "rm -rf", + "Remove a directory and everything in it", + "rmdir /s /q", + True, + NO_CONFIRMATION_WARNING, + ), +) diff --git a/src/flask_day_54/domain/name_demo.py b/src/flask_day_54/domain/name_demo.py new file mode 100644 index 0000000..9a75e11 --- /dev/null +++ b/src/flask_day_54/domain/name_demo.py @@ -0,0 +1,29 @@ +## @file name_demo.py +# @brief Lecture 4 demo of the `__name__ == "__main__"` check. +"""Shows whether a file runs as the main program or as an imported module.""" + +from flask_day_54.domain.constants import ( + IMPORTED_MODULE_SENTENCE, + MAIN_MODULE_NAME, + MAIN_PROGRAM_SENTENCE, +) + + +## @brief Describe how a module is running from its `__name__`. +# @param name The value of `__name__`. +# @return A short sentence. +def describe_name(name: str) -> str: + """Return a sentence telling how the module with this name is running.""" + if name == MAIN_MODULE_NAME: + return MAIN_PROGRAM_SENTENCE + return IMPORTED_MODULE_SENTENCE.format(name=name) + + +## @brief Print the description of this module's own `__name__`. +def main() -> None: + """Print how this file is running; the output is the demo's result.""" + print(describe_name(__name__)) + + +if __name__ == "__main__": + main() diff --git a/src/flask_day_54/presentation/hello.py b/src/flask_day_54/presentation/hello.py index 4483206..329dfec 100644 --- a/src/flask_day_54/presentation/hello.py +++ b/src/flask_day_54/presentation/hello.py @@ -1,10 +1,11 @@ ## @file hello.py -# @brief The minimal Flask application of lectures 1 and 2. -"""The minimal Flask application of lectures 1 and 2.""" +# @brief The minimal Flask application of lectures 1 to 4. +"""The minimal Flask application of lectures 1 to 4.""" from flask import Flask from flask_day_54.application.get_greeting import get_greeting +from flask_day_54.infrastructure.constants import DEBUG, HOST, PORT ## @brief The Flask application object. app = Flask(__name__) @@ -16,3 +17,13 @@ app = Flask(__name__) def hello_world() -> str: """Answer the root route with the greeting.""" return get_greeting() + + +## @brief Start the Flask development server with the configured settings. +def main() -> None: + """Run the development server using the infrastructure settings.""" + app.run(host=HOST, port=PORT, debug=DEBUG) + + +if __name__ == "__main__": + main() diff --git a/tests/e2e/test_hello_main.py b/tests/e2e/test_hello_main.py new file mode 100644 index 0000000..85affce --- /dev/null +++ b/tests/e2e/test_hello_main.py @@ -0,0 +1,33 @@ +import importlib + +import pytest + +flask = pytest.importorskip("flask") + +from flask_day_54.infrastructure.constants import DEBUG, HOST, PORT # noqa: E402 + + +def test_main_runs_app_with_configured_host_port_and_debug( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from flask_day_54.presentation import hello + + calls: list[dict[str, object]] = [] + monkeypatch.setattr(hello.app, "run", lambda **kwargs: calls.append(kwargs)) + + hello.main() + + assert calls == [{"host": HOST, "port": PORT, "debug": DEBUG}] + + +def test_importing_module_does_not_start_server( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from flask_day_54.presentation import hello + + calls: list[object] = [] + monkeypatch.setattr(flask.Flask, "run", lambda *args, **kwargs: calls.append(args)) + + importlib.reload(hello) + + assert calls == [] diff --git a/tests/unit/test_cli_basics.py b/tests/unit/test_cli_basics.py new file mode 100644 index 0000000..f7593ef --- /dev/null +++ b/tests/unit/test_cli_basics.py @@ -0,0 +1,39 @@ +import pytest + +from flask_day_54.domain.cli_basics import ( + describe_command, + destructive_commands, + format_cheat_sheet, +) + + +def test_describe_command_returns_windows_equivalent_when_known() -> None: + assert describe_command("ls").windows_equivalent == "dir" + assert describe_command("touch").windows_equivalent == "type nul > file" + assert describe_command("pwd").windows_equivalent == "cd" + + +def test_describe_command_raises_value_error_when_unknown() -> None: + with pytest.raises(ValueError, match="Unknown command: 'foo'"): + describe_command("foo") + + +def test_destructive_commands_contains_only_rm_variants() -> None: + names = {c.name for c in destructive_commands()} + + assert names == {"rm", "rm -rf"} + + +def test_recursive_remove_has_warning_and_windows_equivalent() -> None: + command = describe_command("rm -rf") + + assert command.windows_equivalent == "rmdir /s /q" + assert command.warning == "No confirmation is asked - double-check the path" + + +def test_format_cheat_sheet_lists_every_command_and_warns_on_rm() -> None: + text = format_cheat_sheet() + + for name in ("pwd", "ls", "cd", "mkdir", "touch", "rm", "rm -rf"): + assert name in text + assert text.count("WARNING") == 2 diff --git a/tests/unit/test_name_demo.py b/tests/unit/test_name_demo.py new file mode 100644 index 0000000..a138483 --- /dev/null +++ b/tests/unit/test_name_demo.py @@ -0,0 +1,17 @@ +from flask_day_54.domain.name_demo import describe_name + + +def test_describe_name_reports_main_program_when_name_is_main() -> None: + assert describe_name("__main__") == ( + "Running as the main program: the file was executed directly" + ) + + +def test_describe_name_reports_imported_module_when_name_is_other() -> None: + assert describe_name("flask_day_54.domain.name_demo") == ( + "Running as an imported module named flask_day_54.domain.name_demo" + ) + + +def test_describe_name_reports_imported_module_when_name_is_empty() -> None: + assert describe_name("") == "Running as an imported module named "