diff --git a/README.md b/README.md index 4662a04..9d5679b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,207 @@ -# 030-nato-phonetic-alphabet +# 🚀 NATO phonetic alphabet +A console tool that spells a word with the NATO phonetic alphabet and handles invalid input with exception handling, the Day 30 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp". It is written for fellow course participants and GitHub visitors who want a readable, tested, runnable solution that has no runtime dependencies. + +![The tool spelling the word Hello][screenshot-spell] + +## 📚 Table of Contents + +- [Overview](#-overview) +- [Requirements](#-requirements) +- [Setup](#-setup) +- [Run](#-run) +- [Tests](#-tests) +- [Continuous integration](#-continuous-integration) +- [Build the source documentation](#-build-the-source-documentation) +- [Project layout](#-project-layout) +- [License](#-license) +- [Links](#-links) +- [Appendix: Project documents](#-appendix-project-documents) + +## 🧭 Overview + +You type a word, the program prints the NATO code word of each letter. A character that is not a letter does not crash the program: the error is caught, you are told to enter letters only, and the program asks again. + +```text +Enter a word: Hello +Phonetic code words: +Hotel +Echo +Lima +Lima +Oscar +``` + +How it works, in the course's terms: + +- `load_nato_dict` reads the supplied CSV file and builds the letter-to-code-word dictionary with a **dictionary comprehension**. +- `spell_word` turns a word into its code words with a **list comprehension** inside a `try` block; a character that is not in the alphabet raises a `KeyError`, which the `except` block turns into an `InvalidWordError`. +- `generate_phonetic` wraps the input and the error handling: it asks for a word, reports an invalid one and asks again until the word is valid. +- The standard library `csv` module replaces Pandas, so the project has no runtime dependencies (see the architecture decision record [ADR-0001][ADR-0001]). + +The wiki explains installation, usage and development in English, Danish and Bahasa Malaysia: [wiki][wiki]. + +## 📋 Requirements + +- Python 3.13 or newer, with the `venv` module. +- Git, to clone the repository. +- Optional: [Doxygen](https://www.doxygen.nl/) to build the source documentation. + +The program itself needs no packages. The development tools (pytest, ruff, mypy, import-linter) are installed by the `dev` extra. + +## 🛠️ Setup + +Clone the repository, then create a local virtual environment named `.venv` in its root, upgrade pip and install the project in editable mode with its development tools. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, allow it for this window only with `Set-ExecutionPolicy -Scope Process RemoteSigned`. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Debian 13 (trixie) ships Python 3.13. On an older release install Python 3.13 first (for example with `pyenv`). + +### MacOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## ▶️ Run + +With the virtual environment active: + +```bash +python -m nato_phonetic_alphabet +``` + +or, as the installed command: + +```bash +nato-phonetic-alphabet +``` + +An invalid character asks for the word again: + +![A word with a digit is rejected, then a valid word is spelled][screenshot-retry] + +## 🧪 Tests + +Run the tests with the virtual environment active: + +```bash +python -m pytest +``` + +The same checks that CI runs: + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## 🔄 Continuous integration + +The workflow [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml) runs on every push to `main` or a `mil-*` branch and on every pull request that touches source, tests or configuration. It sets up Python 3.13, creates a virtual environment, installs the project with the `dev` extra, and runs ruff, mypy and pytest. + +## 📖 Build the source documentation + +The source is documented with Doxygen comments. From the repository root: + +```bash +doxygen Doxyfile +``` + +Open `build/html/index.html` in a browser. The `build/` folder is ignored by git. + +## 🗂️ Project layout + +```text +src/nato_phonetic_alphabet/ + constants.py every literal of the program + main.py composition root and entry point + __main__.py python -m nato_phonetic_alphabet + domain/ spell_word, the spelling rule with try/except (no input or output) + application/ generate_phonetic (input and retry loop) and its port + adapters/ CSV reader and console + data/ nato_phonetic_alphabet.csv +tests/ pytest tests, mirroring src/ +docs/ project documents (see the appendix) +docs/wiki/ wiki pages in en, da and ms +.gitea/workflows/ CI workflow +pyproject.toml project configuration +Doxyfile Doxygen configuration +``` + +## 📄 License + +GNU Affero General Public License v3.0 or later. See [LICENSE](LICENSE). + +## 🔗 Links + +- [Repository][repository] +- [Documentation][documentation] +- [Issue tracker][issues] + +## 📎 Appendix: Project documents + +The documents a newcomer needs, in reading order. + +| Document | What it tells you | +| --- | --- | +| [AGENTS.md][agents] | The rules AI agents follow in this repository | +| [Business Case][BC-001] | Why the project exists, its scope and success criteria | +| [Stakeholder Analysis][SA-001] | Who is involved; the stakeholder IDs used for owners and reviewers | +| [Project Plan][PP-001] | The gateways and their schedule | +| [Milestones][milestones] | One document per gateway: Go/No-Go criteria and tasks | +| [Architecture decisions][adr] | Why the data is read with the standard library and which analysis documents were skipped | +| [Artifact registry][registry] | Where each artifact type lives, the next version, the PO language and domain | +| [Traceability matrix][TM-001] | How the artifacts link and when each was last reviewed | +| [Framework README][framework-readme] | The framework this project uses | +| [Framework changelog][framework-changelog] | What changed in each framework release | + +--- + +[repository]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet +[documentation]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/wiki +[wiki]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/wiki +[issues]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues +[screenshot-spell]: ./docs/images/spell-word.png +[screenshot-retry]: ./docs/images/retry-invalid.png +[agents]: ./AGENTS.md +[BC-001]: ./docs/business-case.md +[SA-001]: ./docs/stakeholder-analysis.md +[PP-001]: ./docs/project-plan.md +[milestones]: ./docs/milestones/ +[adr]: ./docs/adr/ +[ADR-0001]: ./docs/adr/adr-0001-read-nato-data-with-csv-module.md +[registry]: ./docs/artifact-registry.md +[TM-001]: ./docs/sqa/traceability-matrix.md +[framework-readme]: ./framework/README.md +[framework-changelog]: ./framework/CHANGELOG.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 09c7b6f..f45ad13 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -15,7 +15,8 @@ document of a type. `Primary File` may contain a glob (e.g. | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | | MIL | Milestone / Gateway | docs/milestones/*.md | 004 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 001 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 015 | +| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0003 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | | US | User Story | docs/user-stories.md | 002 | diff --git a/docs/images/retry-invalid.png b/docs/images/retry-invalid.png new file mode 100644 index 0000000..eecc21b Binary files /dev/null and b/docs/images/retry-invalid.png differ diff --git a/docs/images/spell-word.png b/docs/images/spell-word.png new file mode 100644 index 0000000..67d815d Binary files /dev/null and b/docs/images/spell-word.png differ diff --git a/docs/milestones/mil-003-documentation-and-publication.md b/docs/milestones/mil-003-documentation-and-publication.md index 2772699..7f2889f 100644 --- a/docs/milestones/mil-003-documentation-and-publication.md +++ b/docs/milestones/mil-003-documentation-and-publication.md @@ -12,6 +12,7 @@ | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | | 2026-10-14 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, adapted from the 026 NATO alphabet project | [80ec1bc] | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Reviewed in RC-005 | pending | --- diff --git a/docs/sqa/reviews/rc-005-mil-003.md b/docs/sqa/reviews/rc-005-mil-003.md new file mode 100644 index 0000000..0961019 --- /dev/null +++ b/docs/sqa/reviews/rc-005-mil-003.md @@ -0,0 +1,65 @@ +# SQA Review Record RC-005: MIL-003 + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-005 | +| CrossReference | [MIL-003], [QC-MIL-001], [QC-LANG-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of MIL-003 | pending | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-003] +- Checklist used: [QC-MIL-001] and [QC-LANG-001] +- Scope: full review +- Language and domain: en / it +- Language reviewer: none (the reviewer reads the language and knows the domain) +- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`) + +## Checklist Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | A concrete deliverable is defined for every gate | Pass | Deliverable section names concrete output: README, screenshots and wiki in three languages. | +| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Go / No-Go table has objectively checkable rows (commands and counts). | +| 3 | Dependencies on other milestones are explicitly mapped | Pass | Dependencies table is filled. | +| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Traceability cites [BC-001] objectives. | +| 5 | Milestone owner and approving reviewer are identified | Pass | Owner and approving reviewer are S01. | +| 6 | Milestone has a defined target date consistent with project constraints | Pass | Target date lies inside the Project Plan window; the Business Case sets no calendar constraint. | + +## Language and Domain Results + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. | +| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. | +| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English; the course title is quoted source text. Checked by the stand-in reviewer, who reads English. | +| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Executive English for this type; the text matches it. | +| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists yet; the terms letter, code word and NATO alphabet are used consistently with no synonyms. Checked by the stand-in; open to challenge. | +| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. | +| 7 | No translated twin (`..md`) exists beside the document | Pass | No translated twin of the file exists. | +| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. | +| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | The domain is software and IT and the language English; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. | +| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers (IDs, tool names). | + +## Overall Verdict + +Go — every Mandatory criterion of QC-MIL-001 and of QC-LANG-001 passes. The review is a stand-in review by the author's AI and is not independent; it is open to challenge in the run summary. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| None | S01 | n/a | + +--- + +[MIL-003]: ../../milestones/mil-003-documentation-and-publication.md +[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md +[QC-LANG-001]: ../../../framework/qc/artifacts/qc-language-domain.md diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md new file mode 100644 index 0000000..72eaf5f --- /dev/null +++ b/docs/sqa/traceability-matrix.md @@ -0,0 +1,77 @@ +# Traceability Matrix + +## Metadata +| Key | Value | +| --- | --- | +| ID | TM-001 | +| CrossReference | [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version, rows for RC-001 to RC-014 | pending | + +--- + +## Purpose + +Tracks backward and forward links between artifact instances so that the cross-artifact traceability can be checked. A row is added or updated whenever an artifact instance is created or reviewed. + +## Traceability Table + +| Artifact Instance | Type | Language | Domain | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | +| --- | --- | --- | --- | --- | --- | --- | +| [BC-001] | Business Case | en | it | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003] | [RC-001] | +| [SA-001] | Stakeholder Analysis | en | it | [BC-001] | [PP-001] | [RC-002] | +| [PP-001] | Project Plan | en | it | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003] | - | +| [MIL-001] | Milestone | en | it | [BC-001], [PP-001] | [MIL-002], [ADR-0001], [ADR-0002] | [RC-003] | +| [MIL-002] | Milestone | en | it | [BC-001], [MIL-001] | [MIL-003], [US-001], [UC-001], [PY-002] | [RC-004] | +| [MIL-003] | Milestone | en | it | [BC-001], [MIL-002] | - | [RC-005] | +| [ADR-0001] | ADR | - | - | [BC-001], [SA-001] | [PY-001] | [RC-006] | +| [ADR-0002] | ADR | - | - | [BC-001] | - | [RC-007] | +| [WF-001] | CI workflow | - | - | [MIL-001] | - | [RC-008] | +| [UCD-001] | Use Case Diagram | en | it | [SA-001], [BC-001] | [US-001], [UC-001] | [RC-010] | +| [US-001] | User Story | en | it | [UCD-001], [MIL-002] | [UC-001] | [RC-011] | +| [UC-001] | Use Case | en | it | [UCD-001], [US-001] | [SSD-001], [PY-002] | [RC-012] | +| [SSD-001] | System Sequence Diagram | en | it | [UC-001] | [PY-002] | [RC-013] | +| [PY-002] | Python source | - | - | [UC-001], [SSD-001], [ADR-0001] | - | [RC-014] | +| [PY-001] | Python source | - | - | [ADR-0001], [MIL-001] | - | [RC-009] | + +## Coverage Notes + +- `-` in Upstream means foundational; in Downstream it means nothing is built on it yet; in Last Reviewed it means no review record exists. +- PP-001 has no QC checklist yet; it is accepted by the Product Owner's stand-in. +- WF-001 and PY-001 are labels for reviewed code instances (no artifact file). +- PY-002 is the label of the reviewed converter code. + +--- + +[BC-001]: ../business-case.md +[MIL-001]: ../milestones/mil-001-repository-foundation.md +[MIL-002]: ../milestones/mil-002-nato-converter.md +[MIL-003]: ../milestones/mil-003-documentation-and-publication.md +[PP-001]: ../project-plan.md +[RC-001]: ./reviews/rc-001-business-case.md +[RC-002]: ./reviews/rc-002-stakeholder-analysis.md +[RC-003]: ./reviews/rc-003-mil-001.md +[RC-004]: ./reviews/rc-004-mil-002.md +[RC-005]: ./reviews/rc-005-mil-003.md +[SA-001]: ../stakeholder-analysis.md +[ADR-0001]: ../adr/adr-0001-read-nato-data-with-csv-module.md +[ADR-0002]: ../adr/adr-0002-skip-analysis-artifacts.md +[WF-001]: ../../.gitea/workflows/ci.yml +[PY-001]: ../../src/nato_phonetic_alphabet/constants.py +[RC-006]: ./reviews/rc-006-adr-0001.md +[RC-007]: ./reviews/rc-007-adr-0002.md +[RC-008]: ./reviews/rc-008-ci-workflow.md +[RC-009]: ./reviews/rc-009-python-skeleton.md +[UCD-001]: ../use-case-diagram.md +[US-001]: ../user-stories.md +[UC-001]: ../uc-001/uc.md +[SSD-001]: ../uc-001/ssd.md +[PY-002]: ../../src/nato_phonetic_alphabet/main.py +[RC-010]: ./reviews/rc-010-ucd-001.md +[RC-011]: ./reviews/rc-011-us-001.md +[RC-012]: ./reviews/rc-012-uc-001.md +[RC-013]: ./reviews/rc-013-ssd-001.md +[RC-014]: ./reviews/rc-014-python-converter.md diff --git a/docs/wiki/Development-da.md b/docs/wiki/Development-da.md new file mode 100644 index 0000000..735c36e --- /dev/null +++ b/docs/wiki/Development-da.md @@ -0,0 +1,47 @@ +# Udvikling + +🌐 [English](Development) · **Dansk** · [Bahasa Melayu](Development-ms) + +Sæt projektet op først ([Installation](Install-da)). Udvidelsen `dev` installerer pytest, ruff, mypy og import-linter. + +## Kør testene + +```bash +python -m pytest +``` + +## Kør de kontroller, CI kører + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Byg kildedokumentationen + +```bash +doxygen Doxyfile +``` + +Åbn `build/html/index.html`. Installér Doxygen fra [doxygen.nl](https://www.doxygen.nl/) eller din pakkehåndtering. + +## Sådan virker exception handling + +`spell_word` (i `domain/spelling.py`) slår hvert bogstav op i ordbogen i en `try`-blok. Et tegn, der ikke findes i alfabetet, giver en `KeyError`, som `except`-blokken gør til en `InvalidWordError`. `generate_phonetic` (i `application/phonetic.py`) fanger fejlen, beder brugeren skrive kun bogstaver og spørger igen, indtil ordet er gyldigt. + +## Kodens opbygning + +| Mappe | Indhold | +| --- | --- | +| `src/nato_phonetic_alphabet/domain/` | Staveregelen, uden input og output | +| `src/nato_phonetic_alphabet/application/` | Use casen og dens porte | +| `src/nato_phonetic_alphabet/adapters/` | CSV-læseren og konsollen | +| `src/nato_phonetic_alphabet/constants.py` | Alle programmets konstanter | +| `tests/` | pytest-tests, som spejler `src/` | + +Afhængigheder peger indad: adapters kender applikationen, applikationen kender domænet. import-linter håndhæver det. + +## Pull requests + +Én gren og én pull request pr. milepæl; CI skal være grøn. Projektet følger SQA- og QC-frameworket i `framework/`; se `docs/` for planen og review-optegnelserne. diff --git a/docs/wiki/Development-ms.md b/docs/wiki/Development-ms.md new file mode 100644 index 0000000..abc50f1 --- /dev/null +++ b/docs/wiki/Development-ms.md @@ -0,0 +1,47 @@ +# Pembangunan + +🌐 [English](Development) · [Dansk](Development-da) · **Bahasa Melayu** + +Sediakan projek dahulu ([Pemasangan](Install-ms)). Pilihan tambahan `dev` memasang pytest, ruff, mypy dan import-linter. + +## Jalankan ujian + +```bash +python -m pytest +``` + +## Jalankan semakan yang dijalankan oleh CI + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Bina dokumentasi sumber + +```bash +doxygen Doxyfile +``` + +Buka `build/html/index.html`. Pasang Doxygen dari [doxygen.nl](https://www.doxygen.nl/) atau pengurus pakej anda. + +## Cara pengendalian pengecualian berfungsi + +`spell_word` (dalam `domain/spelling.py`) mencari setiap huruf dalam kamus di dalam blok `try`. Aksara yang tiada dalam abjad menimbulkan `KeyError`, yang ditukar oleh blok `except` kepada `InvalidWordError`. `generate_phonetic` (dalam `application/phonetic.py`) menangkap ralat itu, meminta pengguna memasukkan huruf sahaja dan bertanya semula sehingga perkataan itu sah. + +## Susun atur kod + +| Folder | Kandungan | +| --- | --- | +| `src/nato_phonetic_alphabet/domain/` | Peraturan ejaan, tanpa input dan output | +| `src/nato_phonetic_alphabet/application/` | Kes guna dan portnya | +| `src/nato_phonetic_alphabet/adapters/` | Pembaca CSV dan konsol | +| `src/nato_phonetic_alphabet/constants.py` | Semua pemalar program | +| `tests/` | Ujian pytest, mencerminkan `src/` | + +Kebergantungan menghala ke dalam: adapter mengenali aplikasi, aplikasi mengenali domain. import-linter menguatkuasakannya. + +## Pull request + +Satu cabang dan satu pull request bagi setiap milestone; CI mesti hijau. Projek ini mengikut rangka kerja SQA dan QC dalam `framework/`; lihat `docs/` untuk pelan dan rekod semakan. diff --git a/docs/wiki/Development.md b/docs/wiki/Development.md new file mode 100644 index 0000000..93209cc --- /dev/null +++ b/docs/wiki/Development.md @@ -0,0 +1,47 @@ +# Development + +🌐 **English** · [Dansk](Development-da) · [Bahasa Melayu](Development-ms) + +Set up the project first ([Install](Install)). The `dev` extra installs pytest, ruff, mypy and import-linter. + +## Run the tests + +```bash +python -m pytest +``` + +## Run the checks that CI runs + +```bash +python -m ruff check . +python -m mypy +lint-imports +``` + +## Build the source documentation + +```bash +doxygen Doxyfile +``` + +Open `build/html/index.html`. Install Doxygen from [doxygen.nl](https://www.doxygen.nl/) or your package manager. + +## How the exception handling works + +`spell_word` (in `domain/spelling.py`) looks every letter up in the dictionary inside a `try` block. A character that is not in the alphabet raises a `KeyError`, which the `except` block turns into an `InvalidWordError`. `generate_phonetic` (in `application/phonetic.py`) catches that error, tells the user to enter letters only and asks again until the word is valid. + +## Code layout + +| Folder | Content | +| --- | --- | +| `src/nato_phonetic_alphabet/domain/` | The spelling rule, with no input or output | +| `src/nato_phonetic_alphabet/application/` | The use case and its ports | +| `src/nato_phonetic_alphabet/adapters/` | The CSV reader and the console | +| `src/nato_phonetic_alphabet/constants.py` | Every literal of the program | +| `tests/` | pytest tests, mirroring `src/` | + +Dependencies point inward: adapters know the application, the application knows the domain. import-linter enforces it. + +## Pull requests + +One branch and one pull request per milestone; CI must be green. The project follows the SQA and QC framework in `framework/`; see `docs/` for the plan and the review records. diff --git a/docs/wiki/Home-da.md b/docs/wiki/Home-da.md new file mode 100644 index 0000000..b24e4bc --- /dev/null +++ b/docs/wiki/Home-da.md @@ -0,0 +1,23 @@ +# Det fonetiske NATO-alfabet + +🌐 [English](Home) · **Dansk** · [Bahasa Melayu](Home-ms) + +Et konsolprogram, der staver et ord med det fonetiske NATO-alfabet. Det er opgaven fra dag 30 i Udemys "100 Days of Code: The Complete Python Pro Bootcamp" og viser exception handling: input, der ikke er et bogstav, fanges med `try` og `except` i stedet for at få programmet til at gå ned. Det kræver Python 3.13 eller nyere og har ingen runtime-afhængigheder. + +![Programmet staver ordet Hello](images/spell-word.png) + +| Side | Læs den, når du vil | +| --- | --- | +| [Installation](Install-da) | Oprette et lokalt `.venv` og installere projektet på Windows, Linux eller macOS | +| [Brug](Usage-da) | Køre programmet og læse dets output | +| [Udvikling](Development-da) | Køre testene og kontrollerne og bygge kildedokumentationen | + +## Hvem det er til + +- **Kursister**, der vil have en læsbar løsning med opgavens funktionsnavne (`load_nato_dict`, `generate_phonetic`) at sammenligne med deres egen. +- **GitHub-besøgende**, der vil se et lille, testet Python-projekt uden runtime-afhængigheder. + +## Links + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet) +- [Fejl og ønsker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues) diff --git a/docs/wiki/Home-ms.md b/docs/wiki/Home-ms.md new file mode 100644 index 0000000..e08ac37 --- /dev/null +++ b/docs/wiki/Home-ms.md @@ -0,0 +1,23 @@ +# Abjad fonetik NATO + +🌐 [English](Home) · [Dansk](Home-da) · **Bahasa Melayu** + +Alat konsol yang mengeja satu perkataan dengan abjad fonetik NATO. Ia ialah tugasan hari ke-30 dalam "100 Days of Code: The Complete Python Pro Bootcamp" di Udemy dan menunjukkan pengendalian pengecualian (exception handling): input yang bukan huruf ditangkap dengan `try` dan `except` dan bukannya menyebabkan program terhenti. Ia memerlukan Python 3.13 atau lebih baharu dan tidak mempunyai kebergantungan masa jalan. + +![Alat mengeja perkataan Hello](images/spell-word.png) + +| Halaman | Baca apabila anda mahu | +| --- | --- | +| [Pemasangan](Install-ms) | Mencipta `.venv` setempat dan memasang projek di Windows, Linux atau macOS | +| [Penggunaan](Usage-ms) | Menjalankan program dan membaca outputnya | +| [Pembangunan](Development-ms) | Menjalankan ujian dan semakan serta membina dokumentasi sumber | + +## Untuk siapa + +- **Peserta kursus** yang mahukan penyelesaian yang mudah dibaca dengan nama fungsi tugasan (`load_nato_dict`, `generate_phonetic`) untuk dibandingkan dengan penyelesaian sendiri. +- **Pelawat GitHub** yang mahukan projek Python kecil yang diuji tanpa kebergantungan masa jalan. + +## Pautan + +- [Repositori](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet) +- [Penjejak isu](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues) diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..388bbca --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,23 @@ +# NATO phonetic alphabet + +🌐 **English** · [Dansk](Home-da) · [Bahasa Melayu](Home-ms) + +A console tool that spells a word with the NATO phonetic alphabet. It is the Day 30 assignment of Udemy's "100 Days of Code: The Complete Python Pro Bootcamp" and shows exception handling: input that is not a letter is caught with `try` and `except` instead of crashing the program. It needs Python 3.13 or newer and has no runtime dependencies. + +![The tool spelling the word Hello](images/spell-word.png) + +| Page | Read it when you want to | +| --- | --- | +| [Install](Install) | Create a local `.venv` and install the project on Windows, Linux or macOS | +| [Usage](Usage) | Run the program and read its output | +| [Development](Development) | Run the tests, the checks and build the source documentation | + +## Who it is for + +- **Course participants** who want a readable solution with the assignment's function names (`load_nato_dict`, `generate_phonetic`) to compare with their own. +- **GitHub viewers** who want a small, tested Python project with no runtime dependencies. + +## Links + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet) +- [Issue tracker](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet/issues) diff --git a/docs/wiki/Install-da.md b/docs/wiki/Install-da.md new file mode 100644 index 0000000..8b0538b --- /dev/null +++ b/docs/wiki/Install-da.md @@ -0,0 +1,57 @@ +# Installation + +🌐 [English](Install) · **Dansk** · [Bahasa Melayu](Install-ms) + +## Det skal du bruge + +- Python 3.13 eller nyere med modulet `venv` +- Git + +## Trin + +Alle systemer gør de samme fire ting: klon repository'et, opret et virtuelt miljø kaldet `.venv`, opgradér pip og installér projektet. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Hvis PowerShell afviser aktiveringsscriptet, så kør først `Set-ExecutionPolicy -Scope Process RemoteSigned`. Det gælder kun for det vindue. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Tjek at det virker + +```bash +python -m nato_phonetic_alphabet +``` + +Skriv et ord. Du skal se dets kodeord. Næste side: [Brug](Usage-da). diff --git a/docs/wiki/Install-ms.md b/docs/wiki/Install-ms.md new file mode 100644 index 0000000..c8003cc --- /dev/null +++ b/docs/wiki/Install-ms.md @@ -0,0 +1,57 @@ +# Pemasangan + +🌐 [English](Install) · [Dansk](Install-da) · **Bahasa Melayu** + +## Apa yang diperlukan + +- Python 3.13 atau lebih baharu dengan modul `venv` +- Git + +## Langkah + +Semua sistem melakukan empat perkara yang sama: klon repositori, cipta persekitaran maya bernama `.venv`, naik taraf pip dan pasang projek. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Jika PowerShell enggan menjalankan skrip pengaktifan, jalankan `Set-ExecutionPolicy -Scope Process RemoteSigned` dahulu. Ia hanya terpakai pada tetingkap itu. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Semak ia berfungsi + +```bash +python -m nato_phonetic_alphabet +``` + +Masukkan satu perkataan. Anda akan melihat kata kodnya. Seterusnya: [Penggunaan](Usage-ms). diff --git a/docs/wiki/Install.md b/docs/wiki/Install.md new file mode 100644 index 0000000..8932fd7 --- /dev/null +++ b/docs/wiki/Install.md @@ -0,0 +1,57 @@ +# Install + +🌐 **English** · [Dansk](Install-da) · [Bahasa Melayu](Install-ms) + +## What you need + +- Python 3.13 or newer with the `venv` module +- Git + +## Steps + +Every system does the same four things: clone the repository, create a virtual environment called `.venv`, upgrade pip, install the project. + +### Windows PowerShell + +```powershell +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +py -3.13 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +If PowerShell refuses to run the activation script, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first. It only applies to that window. + +### Linux Debian + +```bash +sudo apt install git python3 python3-venv +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +### macOS + +```bash +brew install python@3.13 git +git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet.git +cd 030-nato-phonetic-alphabet +python3.13 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +## Check that it works + +```bash +python -m nato_phonetic_alphabet +``` + +Enter a word. You should see its code words. Next: [Usage](Usage). diff --git a/docs/wiki/Usage-da.md b/docs/wiki/Usage-da.md new file mode 100644 index 0000000..3fdc97a --- /dev/null +++ b/docs/wiki/Usage-da.md @@ -0,0 +1,31 @@ +# Brug + +🌐 [English](Usage) · **Dansk** · [Bahasa Melayu](Usage-ms) + +Aktivér det virtuelle miljø (se [Installation](Install-da)), og start programmet: + +```bash +python -m nato_phonetic_alphabet +``` + +Den installerede kommando gør det samme: + +```bash +nato-phonetic-alphabet +``` + +## Stav et ord + +Programmet spørger efter et ord og skriver NATO-kodeordet for hvert bogstav i rækkefølge. Store og små bogstaver giver samme resultat. + +![Programmet staver ordet Hello](images/spell-word.png) + +## Ugyldigt input + +Et ciffer, et mellemrum eller et tegn er ikke et bogstav. Programmet siger det og spørger igen. + +![Et ord med et ciffer afvises, derefter staves et gyldigt ord](images/retry-invalid.png) + +## Tryk Ctrl+C eller Ctrl+D + +Afslutter du inputtet (Ctrl+D på Linux og macOS, Ctrl+Z og Enter på Windows) eller trykker Ctrl+C, lukker programmet stille. diff --git a/docs/wiki/Usage-ms.md b/docs/wiki/Usage-ms.md new file mode 100644 index 0000000..48c746f --- /dev/null +++ b/docs/wiki/Usage-ms.md @@ -0,0 +1,31 @@ +# Penggunaan + +🌐 [English](Usage) · [Dansk](Usage-da) · **Bahasa Melayu** + +Aktifkan persekitaran maya (lihat [Pemasangan](Install-ms)), kemudian mulakan program: + +```bash +python -m nato_phonetic_alphabet +``` + +Arahan yang dipasang melakukan perkara yang sama: + +```bash +nato-phonetic-alphabet +``` + +## Eja satu perkataan + +Program meminta satu perkataan dan mencetak kata kod NATO bagi setiap huruf mengikut urutan. Huruf besar dan huruf kecil memberi keputusan yang sama. + +![Alat mengeja perkataan Hello](images/spell-word.png) + +## Input tidak sah + +Angka, ruang atau tanda baca bukan huruf. Program memberitahu perkara itu dan bertanya semula. + +![Perkataan dengan angka ditolak, kemudian perkataan yang sah dieja](images/retry-invalid.png) + +## Tekan Ctrl+C atau Ctrl+D + +Menamatkan input (Ctrl+D di Linux dan macOS, Ctrl+Z kemudian Enter di Windows) atau menekan Ctrl+C menutup program dengan senyap. diff --git a/docs/wiki/Usage.md b/docs/wiki/Usage.md new file mode 100644 index 0000000..7e696f1 --- /dev/null +++ b/docs/wiki/Usage.md @@ -0,0 +1,31 @@ +# Usage + +🌐 **English** · [Dansk](Usage-da) · [Bahasa Melayu](Usage-ms) + +Activate the virtual environment (see [Install](Install)), then start the program: + +```bash +python -m nato_phonetic_alphabet +``` + +The installed command does the same: + +```bash +nato-phonetic-alphabet +``` + +## Spell a word + +The program asks for a word and prints the NATO code word of each letter, in order. Upper and lower case give the same result. + +![The tool spelling the word Hello](images/spell-word.png) + +## Invalid input + +A digit, a space or a punctuation mark is not a letter. The program says so and asks again. + +![A word with a digit is rejected, then a valid word is spelled](images/retry-invalid.png) + +## Press Ctrl+C or Ctrl+D + +Ending the input (Ctrl+D on Linux and macOS, Ctrl+Z then Enter on Windows) or pressing Ctrl+C closes the program quietly. diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..f889c64 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,24 @@ +**NATO phonetic alphabet** + +- [Home](Home) +- [Install](Install) +- [Usage](Usage) +- [Development](Development) + +**Dansk** + +- [Hjem](Home-da) +- [Installation](Install-da) +- [Brug](Usage-da) +- [Udvikling](Development-da) + +**Bahasa Melayu** + +- [Utama](Home-ms) +- [Pemasangan](Install-ms) +- [Penggunaan](Usage-ms) +- [Pembangunan](Development-ms) + +**Links** + +- [Repository](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/030-nato-phonetic-alphabet) diff --git a/docs/wiki/images/retry-invalid.png b/docs/wiki/images/retry-invalid.png new file mode 100644 index 0000000..eecc21b Binary files /dev/null and b/docs/wiki/images/retry-invalid.png differ diff --git a/docs/wiki/images/spell-word.png b/docs/wiki/images/spell-word.png new file mode 100644 index 0000000..67d815d Binary files /dev/null and b/docs/wiki/images/spell-word.png differ