Paddy
e3bbd4d264
CartoDB's positron basemap now renders an "API KEY REQUIRED" watermark. Use tiles="OpenStreetMap" via a new MAP_TILES constant instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# 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.
|
||
|
||
## CartoDB "positron" tiles now require an API key (2026-09-07)
|
||
|
||
The original `folium.Map(tiles="CartoDB positron")` started rendering an
|
||
"API KEY REQUIRED / carto.com/basemaps/apikey" watermark – Carto moved its
|
||
basemaps behind a key. Switched to `tiles="OpenStreetMap"` (constant
|
||
`MAP_TILES`), which needs no key. Trade-off: OSM standard tiles are more
|
||
colourful than positron's muted grey. Other no-key options if a lighter look is
|
||
wanted: OSM Germany (`tile.openstreetmap.de`), OSM France Hot
|
||
(`{s}.tile.openstreetmap.fr/hot`) – both still colourful. Truly muted
|
||
key-free basemaps are hard to find now.
|
||
|
||
Don't assume a "free" third-party tile source stays free – pin the provider in
|
||
one constant so swapping it is a one-line change.
|
||
|
||
## 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.
|