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()

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,
+    ),
+)

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()

src/flask_day_54/presentation/hello.py

@@ -1,10 +1,11 @@
 ## @file hello.py
-#  @brief 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 and 2."""
+"""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()

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 == []

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

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 "