drk-blutspende-orte/docs/dev-notes.md

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:

/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.

Map tiles: Carto needs a key, OSM 403s file:// — use Esri (2026-09-07)

Two dead ends before landing on Esri:

1. folium.Map(tiles="CartoDB positron") → "API KEY REQUIRED" watermark; Carto moved basemaps behind a key.
2. tiles="OpenStreetMap" → worked in curl from the dev machine but the user's browser got HTTP 403 "referer is required by tile usage policy". OSM's tile CDN graylists refererless requests, and a karte.html opened as a local file:// sends no Referer. A browser can't add one. Dead end for this app's "open a local HTML file" model.

Now: Esri "World Light Gray" base + reference (labels) overlay (server.arcgisonline.com/ArcGIS/rest/services/Canvas/…). No key, no Referer check, light/muted look close to the old positron. MAP_TILES / MAP_TILES_LABELS constants; comment lists Esri Street/Topo as swaps.

Lesson: a tile source that works from curl or an http:// page can still fail from file://. Test the map by opening the generated karte.html directly, not just by checking the URL in the HTML.

Tk popup menus: bind <ButtonRelease-3>, not <Button-3> (2026-09-07)

widget.bind("<Button-3>", …) + menu.tk_popup(x, y) + finally: menu.grab_release() is the Windows idiom and misfires on X11: tk_popup returns immediately, grab_release() drops the menu's grab, and the pending <ButtonRelease-3> then activates whatever entry is under the cursor (the first one). Symptom here: right-click a history row → menu flashes → edit dialog opens.

Rules for this codebase:

• bind the release event: RIGHT_CLICK constant (<ButtonRelease-3>, or <ButtonRelease-2> on macOS),
• build each context menu once (store on self), don't recreate per click,
• just call menu.tk_popup(...) — no grab_release().

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.