54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
# ADR-0001: Standard library first, speech as an optional extra
|
|
|
|
## Metadata
|
|
| Key | Value |
|
|
| --- | --- |
|
|
| ID | ADR-0001 |
|
|
| CrossReference | [BC-001], [SA-001] |
|
|
|
|
## Version History
|
|
| Date | Status | Author | Reviewer | Change | Commit |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [c3fbcbc] |
|
|
|
|
Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
The assignment tells the participant to read the word list with `pandas`. The Product Owner (S01) also wants the Malay word spoken, which needs `gTTS` and `playsound`. GitHub viewers (S03) want no runtime dependencies, and fellow course participants (S02) want a program they can run at once. Options:
|
|
|
|
1. `pandas` for CSV and `gTTS` plus `playsound` as normal dependencies: matches the assignment text, but installs a large dependency tree for a 1000 row file, and a failing `playsound` build breaks the install.
|
|
2. Standard library `csv` for the data and `gTTS` plus `playsound` as an optional extra behind a port: no runtime dependency for the core program, speech available on request.
|
|
3. No speech at all: simplest, but does not meet the Product Owner's wish.
|
|
|
|
## Decision
|
|
|
|
The core program uses only the Python standard library (`csv`, `tkinter`, `random`, `pathlib`). Speech is an optional extra declared as `speech` in `pyproject.toml` (`pip install -e ".[speech]"`), used through a `SpeechPort`, and replaced by a silent adapter when the extra or the network is missing.
|
|
|
|
## Consequences
|
|
|
|
**Positive:**
|
|
|
|
- `dependencies` in `pyproject.toml` is empty, which meets success criterion 3 of [BC-001] and the concern of S03.
|
|
- The program and its tests run without a network.
|
|
- A broken audio player cannot stop the program from starting.
|
|
|
|
**Negative:**
|
|
|
|
- The code differs from the assignment text, which uses `pandas`; the wiki explains the mapping for S02.
|
|
- Two code paths exist for speech (real and silent) and both need tests.
|
|
- `playsound` is unmaintained and is pinned to 1.2.2.
|
|
|
|
## Affected Artifacts
|
|
|
|
- [BC-001] — success criterion 3 and the risk about `playsound`
|
|
- [SA-001] — the conflict between S01 and S03
|
|
|
|
---
|
|
|
|
[BC-001]: ../business-case.md
|
|
[SA-001]: ../stakeholder-analysis.md
|
|
[c3fbcbc]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/c3fbcbcfaf799e0ae34aed7e14d3bc8a62f03db3
|