# Dev notes — assumptions that turned out wrong

Running list so the same mistakes aren't repeated. Add to it whenever reality
contradicts an assumption.

## The macOS system Python can't run the GUI; use a Homebrew Python (2026-09-07)

The macOS **CommandLineTools** Python 3.9 (`/Library/Developer/CommandLineTools/
.../python3.9`) ships **Tk 8.5.9**. `ttkbootstrap` 1.10.1 requires **Tk 8.6+**.
Symptoms: `TclError: couldn't recognize image data` (window icon) and
`TclError: unknown option "-style"` on `ttk.Scrollbar`.

**Fix for local GUI testing:** `brew install python-tk@3.12` (pulls `tcl-tk`,
gives Python 3.12 + **Tk 9.0**), then:

```bash
/opt/homebrew/bin/python3.12 -m venv venv
venv/bin/pip install -r requirements.txt
venv/bin/python app.py
```

`ttkbootstrap` 1.10.1 runs fine on Tk 9.0 in practice (verified: window builds,
Treeview sort, DateEntry, LabelFrame, custom styles all work).

- The **Linux Mint target** uses its own `python3-tk` (Tk 8.6+) and is
  unaffected either way.
- `screencapture` from a non-GUI shell fails ("could not create image from
  display") without Screen-Recording permission — automated screenshots of the
  running app aren't available here; verify by building the widget tree and
  driving it programmatically instead.

## `pandas` reads everything as strings by design

`DataStore._load` uses `dtype={...: str}` for `postal_code`, `lat`, `lon`.
Numeric parsing is deliberately deferred to `get_map_data` (`pd.to_numeric(...,
errors="coerce")`). Don't "fix" columns to float on load — blank coordinates and
leading-zero PLZ both depend on the string representation.

## Nominatim query order matters

`geocode_city` returns the **first** hit, trying PLZ-qualified first, then each
region in `GEOCODE_REGIONS`, then a bare `", Germany"`. Reordering changes which
coordinates ambiguous town names resolve to.