A flash card program for learning the most frequent Malay words with their Danish translations. It is the solution of day 31 of Udemy's 100 Days of Code: The Complete Python Pro Bootcamp, written for course participants who want to compare solutions and for visitors who browse the repository for ideas.

🧭 Overview

The program first asks for a level: the first 100 words, the first 1000 words or all words of the word list, which is ordered from the most to the least frequent word. Then it shows a Malay word on a card. After three seconds the card turns over and shows the Danish translation. You press the green tick when you know the word and the red cross when you do not. A known word is removed from the words to learn, and the words still to learn are saved, so the next start continues where you stopped.

Part	What it is for
`src/flash_card/`	The program, in four layers: `domain`, `application`, `infrastructure`, `presentation`
`tests/`	`pytest` tests: `unit`, `integration`, `e2e`
`data/`	The word list `ms-da.csv` and, after the first known word, your own `words_to_learn.csv`
`docs/`	Project documents (business case, plan, design, review records), `docs/wiki/` and `docs/images/`
`tools/`	Helper scripts: `generate_images.py`, `capture_screenshots.py` and `build_executable.py`
`Doxyfile`	Doxygen configuration for the source code documentation

The core program uses only the Python standard library. Spoken Malay words are an optional extra.

Screenshots

Choose your level	Front: the Malay word	Back: the Danish translation after 3 seconds

Where is each assignment step?

Assignment step	Code
1. User interface	`FlashCardView.__init__` in `src/flash_card/presentation/features/flash_card/flash_card_view.py`; images made by `tools/generate_images.py`
2. New flash cards	`CsvVocabularyRepository` (the standard library `csv` instead of `pandas`), `Deck.draw`, `StudySession.next_card`, `FlashCardView.next_card`
3. Flip the cards	`FlashCardView.flip_card` and `FlashCardView.flip_timer` (`after`, `after_cancel`), `FlashCardViewModel.flip_card`
4. Save your progress	`FlashCardView.is_known`, `StudySession.mark_known`, `CsvProgressRepository`
Extra: level choice	`LevelView`, `LevelViewModel`, `Level`, `Deck.within`, `StudySession.next_card`, `open_study_session`
Extra: spoken word	`GttsSpeech`, `NullSpeech`, `build_speech` in `presentation/app.py`

The wiki (English, Dansk, Bahasa Malaysia) explains the same in three languages.

Data

data/ms-da.csv holds 1000 frequent Malay words with a Danish machine translation; see data/README.md for the format and origin.

📋 Requirements

Need	Why
Python 3.13 or later, with Tkinter	The program and its window (Tkinter is part of the standard Python installers for Windows and macOS; on Debian or Ubuntu install `python3-tk`)
`git`	To clone the repository
Doxygen (optional)	To build the source code documentation
`pyinstaller` (optional, extra `build`)	To build a single executable file (see Run)
`gTTS` and `playsound==1.2.2` (optional, extra `speech`)	To hear the Malay word; needs a network connection

🛠️ Setup

Create a virtual environment in .venv, activate it, upgrade pip and install the project. Run the commands in the repository folder.

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Linux and macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Use python -m pip install -e . if you only want to run the program; the dev extra adds pytest, ruff, mypy and import-linter.
Add the spoken word with python -m pip install -e ".[speech]".
If PowerShell refuses to run Activate.ps1, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, or use .\.venv\Scripts\activate.bat in cmd.
Leave the environment with deactivate. Delete the .venv folder to start over.

▶️ Run

python -m flash_card

The program is run from the activated .venv. The window opens with the level screen: choose 100 words, 1000 words or All words. Then a card appears. Press the green tick for a word you know and the red cross for a word you do not. Options:

Option	Meaning
`--data-dir <folder>`	Folder with `ms-da.csv` and `words_to_learn.csv`
`--level {100,1000,all}`	Start at that level and skip the level screen
`--no-speech`	Do not speak the Malay word

Known words stay known at every level: the level only limits which of the words you do not know yet come up. To start again, delete data/words_to_learn.csv or use the menu.

Menu	Command	What it does
File	Open...	Opens another word list from a CSV file (header with two language codes, for example `en;da`). Progress is kept apart for each list
File	Change level...	Shows the level choice again without a restart; known words stay known
File	Reset word list...	After a confirmation removes the progress of the open list, so all its words are to learn again; the list file is not changed
File	Exit	Closes the program
About	Contact	The author, Jens Tirsvad Nielsen, Software engineer; opens the LinkedIn page in your browser

The progress of the delivered ms-da.csv is data/words_to_learn.csv; another list gets data/words_to_learn_<name>.csv. The opened list is not remembered after a restart.

Executable (Windows, no Python needed to run it)

The release pages of v0.2.0 and v0.1.0 have the release notes. The executable is not attached there yet, because the server's upload limit rejects a file of this size (HTTP 413). Build it yourself:

python -m pip install -e ".[build,speech]"
python tools/build_executable.py

The script builds dist/flash-card.exe: one file, no console window, with the images, the word list and the spoken word inside. Open it by double-clicking. It keeps your progress in a data/ folder next to the executable (data/words_to_learn.csv); a data/ms-da.csv next to it replaces the word list inside. Add --no-speech to the build script to leave the speech packages out. The executable is a build output and is not committed; build it on the system you want to run it on (Windows, Linux or macOS).

🧪 Tests

python -m pytest

Quality checks used by the project:

python -m ruff check src tests
python -m mypy
lint-imports

The window test in tests/e2e/ is skipped when no display is available.

Build the source code documentation (Doxygen comments) with doxygen Doxyfile; the HTML is written to docs/doxygen/html/. The screenshots are made with python tools/capture_screenshots.py after python -m pip install -e ".[tools]" (Pillow, tool only).

Checks without a desktop (Docker)

The tests, the linters, the screenshots and a smoke test of a Linux binary run in a Debian container on a virtual screen, so no window opens on your own desktop.

docker build -f docker/debian.Dockerfile -t flash-card-debian .
# linters and the whole test suite, including the real window tests
docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
# screenshots into ./build/container-out
docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
# build the Linux binary and press the known button 5 times (binary and source)
docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5

On Windows PowerShell write ${PWD} for $PWD. The repository is mounted read-only and copied inside the container.

The desktop is Xvfb with GNOME's window manager (mutter). GNOME Shell is tried first and does not start in a container (it needs a login manager), so the scripts fall back to mutter and print which one ran.
The Windows executable is checked in Windows Sandbox (Windows 11 Pro, feature enabled): powershell -File tools\sandbox\run.ps1 -Runs 5 after python tools/build_executable.py. The sandbox shows its own window while it runs; the click is made inside the sandbox.
Not covered: macOS (it cannot be run in Docker on Windows or Linux and Apple's licence allows it only on Apple hardware), and Windows itself in the Debian container.

📄 License

GNU Affero General Public License v3.0 or later. See LICENSE.

🔗 Links

Repository
Documentation
Issue tracker
Releases (v0.2.0 and v0.1.0: release notes; the executable is built from source, see Run)

📎 Appendix: Project documents

The documents a newcomer needs, in reading order.

Document	What it tells you
AGENTS.md	The rules AI agents follow in this repository
Business Case	Why the project exists, its scope and success criteria
Stakeholder Analysis	Who is involved; the stakeholder IDs used for owners and reviewers
Project Plan	The gateways and their schedule
Milestones	One document per gateway: Go/No-Go criteria and tasks
Artifact registry	Where each artifact type lives, the next version, the PO language and domain
Domain dictionary	The PO terms and the IT terms
Traceability matrix	How the artifacts link and when each was last reviewed
Framework README	The framework this project uses
Framework changelog	What changed in each framework release

README.md

🚀 Flash Card