MIL-001: project foundation

pyproject.toml (Python >=3.13, no runtime dependencies, speech and dev extras),
Python .gitignore, layer skeleton with constants.py, Doxyfile, README with the
.venv instructions, the Malay to Danish word list and review record RC-023.

Task: MIL-001#1
Task: MIL-001#2
Task: MIL-001#3
Task: MIL-001#4
Task: MIL-001#5
Task: MIL-001#6

src/flash_card/__init__.py

@@ -0,0 +1,7 @@
+"""Flash card program that teaches Malay words with Danish translations.
+
+@file __init__.py
+@brief Package root of the flash card program.
+"""
+
+__version__ = "0.1.0"

src/flash_card/__main__.py

@@ -0,0 +1,10 @@
+"""Run the flash card program with ``python -m flash_card``.
+
+@file __main__.py
+@brief Module entry point that calls the presentation layer.
+"""
+
+from flash_card.presentation.app import run
+
+if __name__ == "__main__":
+    run()

src/flash_card/application/__init__.py

@@ -0,0 +1,5 @@
+"""Application layer: use cases and ports.
+
+@file __init__.py
+@brief Holds use cases and the ports they need; may import only the domain layer.
+"""

src/flash_card/constants.py

@@ -0,0 +1,74 @@
+"""All constants of the flash card program, defined once.
+
+@file constants.py
+@brief Window, card, font, language, file and asset constants.
+Imports only the standard library.
+"""
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Final
+
+## @brief Window background colour.
+BACKGROUND_COLOR: Final[str] = "#B1DDC6"
+## @brief Window title.
+WINDOW_TITLE: Final[str] = "Flashy"
+## @brief Padding around the card in pixels.
+WINDOW_PADDING: Final[int] = 50
+
+## @brief Card width in pixels.
+CARD_WIDTH: Final[int] = 800
+## @brief Card height in pixels.
+CARD_HEIGHT: Final[int] = 526
+## @brief Horizontal centre of the card in pixels.
+CARD_CENTER_X: Final[int] = 400
+## @brief Vertical position of the language text in pixels.
+LANGUAGE_TEXT_Y: Final[int] = 150
+## @brief Vertical position of the word text in pixels.
+WORD_TEXT_Y: Final[int] = 263
+## @brief Delay before the card flips, in milliseconds.
+FLIP_DELAY_MS: Final[int] = 3000
+
+## @brief Font of the language text: family, size, style.
+LANGUAGE_FONT: Final[tuple[str, int, str]] = ("Arial", 40, "italic")
+## @brief Font of the word text: family, size, style.
+WORD_FONT: Final[tuple[str, int, str]] = ("Arial", 60, "bold")
+## @brief Text colour on the card front.
+FRONT_TEXT_COLOR: Final[str] = "black"
+## @brief Text colour on the card back.
+BACK_TEXT_COLOR: Final[str] = "white"
+
+## @brief Display names by language code; the caller shows unknown codes in upper case.
+LANGUAGE_NAMES: Final[Mapping[str, str]] = {"ms": "Malay", "da": "Danish"}
+## @brief Message shown when no word is left to learn.
+FINISHED_MESSAGE: Final[str] = "Nothing left to learn"
+## @brief Language name shown before the first card.
+PLACEHOLDER_LANGUAGE_NAME: Final[str] = "Malay"
+## @brief Word shown before the first card.
+PLACEHOLDER_WORD: Final[str] = "kata"
+
+## @brief Delimiter of the CSV files.
+CSV_DELIMITER: Final[str] = ";"
+## @brief Encoding of the CSV files.
+CSV_ENCODING: Final[str] = "utf-8"
+## @brief File name of the vocabulary.
+VOCABULARY_FILE_NAME: Final[str] = "ms-da.csv"
+## @brief File name of the words still to learn.
+PROGRESS_FILE_NAME: Final[str] = "words_to_learn.csv"
+## @brief Language code used for speech.
+SPEECH_LANGUAGE_CODE: Final[str] = "ms"
+
+## @brief Root folder of the project.
+PROJECT_ROOT: Final[Path] = Path(__file__).resolve().parents[2]
+## @brief Default folder of the data files.
+DEFAULT_DATA_DIR: Final[Path] = PROJECT_ROOT / "data"
+## @brief Folder of the image assets.
+ASSETS_DIR: Final[Path] = Path(__file__).resolve().parent / "presentation" / "assets"
+## @brief File name of the card front image.
+CARD_FRONT_IMAGE_NAME: Final[str] = "card_front.png"
+## @brief File name of the card back image.
+CARD_BACK_IMAGE_NAME: Final[str] = "card_back.png"
+## @brief File name of the right button image.
+RIGHT_IMAGE_NAME: Final[str] = "right.png"
+## @brief File name of the wrong button image.
+WRONG_IMAGE_NAME: Final[str] = "wrong.png"

src/flash_card/domain/__init__.py

@@ -0,0 +1,6 @@
+"""Domain layer: entities and rules of the flash card program.
+
+@file __init__.py
+@brief Holds entities, value objects and rules.
+May import nothing outside the standard library.
+"""

src/flash_card/infrastructure/__init__.py

@@ -0,0 +1,5 @@
+"""Infrastructure layer: adapters for files, speech and other outside systems.
+
+@file __init__.py
+@brief Holds implementations of ports; may import the application and domain layers.
+"""

src/flash_card/presentation/__init__.py

@@ -0,0 +1,5 @@
+"""Presentation layer: views, view models and the entry point.
+
+@file __init__.py
+@brief Holds the user interface and the composition root; may import every inner layer.
+"""

src/flash_card/presentation/app.py

@@ -0,0 +1,28 @@
+"""Entry point of the flash card program.
+
+@file app.py
+@brief Starts the program; the window arrives in MIL-002.
+"""
+
+from collections.abc import Sequence
+from typing import NoReturn
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the program and return its exit code.
+
+    The window arrives in MIL-002; for now nothing happens.
+
+    @param argv Command line arguments, or None for none.
+    @return The exit code, 0 on success.
+    """
+    return 0
+
+
+def run() -> NoReturn:
+    """Run the program and exit the interpreter with its exit code.
+
+    @return Never returns; the function always raises SystemExit.
+    @throws SystemExit Always, with the exit code of main.
+    """
+    raise SystemExit(main())