h3cx/dpg-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

step 8: harden docs and prepare rebuilt beta

Browse Source
This commit is contained in:
Hector van der Aa
2026-05-23 10:47:34 +02:00
parent d0ba8c4218
commit 50e38e18ee
17 changed files with 653 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
AGENTS.md
View File

@@ -2,7 +2,7 @@
## Current status
Step 6 complete.
Step 8 complete.
## Completed steps
@@ -12,10 +12,12 @@ Step 3 - Widget shell, sizing system, and GUI-thread frame pump.
Step 4 - Tile manager, persistent cache, and asynchronous loading.
Step 5 - Interaction: pan, zoom, and view commands.
Step 6 - Overlay rendering and runtime update stress tests.
Step 7 - Layers, provider switching, and clearing APIs.
Step 8 - Documentation, hardening, and internal release.
## Current step
Step 7 - Layers, provider switching, and clearing APIs.
Internal rebuilt beta prepared.
## Design decisions
@@ -94,7 +96,34 @@ None yet.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran a Dear PyGui context smoke check for `map_widget` with marker, polyline, and trajectory overlays.
- Added `z_index` support for `add_layer`, layer visibility/clearing tests, and cache-safe map-wide memory clearing.
- Implemented provider switching that validates providers, clamps zoom to the new provider range, preserves overlays/center, increments generation, and queues GUI-thread tile invalidation.
- Implemented provider-scoped disk cache clearing and cache-size scanning.
- Exported `CacheStats` publicly.
- Added `examples/custom_provider.py` and cache control/stat buttons to `examples/cache_stress.py`.
- Updated `README.md` with Step 7 behavior and examples.
- Added Step 7 tests for provider switch tile invalidation, provider-scoped disk clearing, queued disk clear commands, layer z-order updates, and public exports.
- Ran `uv run ruff format .`.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Ran `uv run python -c "import dpg_map as dpgm; print(dpgm.list_providers())"`.
- Added docstrings for public API functions.
- Rewrote `README.md` with uv install, local editable dependency, basic usage, sizing, live update, custom provider, cache, OpenStreetMap, and thread-safety documentation.
- Added Step 8 hardening tests for unknown maps, overlays, providers, invalid coordinates, mismatched coordinate lengths, empty trajectory support, deleted overlays, provider switching while tiles are loading, overlay updates during dragging, and public docstrings.
- Bumped package version to `0.3.0b1` and updated the fallback OpenStreetMap User-Agent version.
- Ran `uv run pytest`.
- Ran `uv run ruff format .`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Tested editable install from `/tmp/dpg-map-editable-test` with `uv add --editable /home/hector/projects/dpg-map`.
- Ran editable install import check: `uv run python -c "import dpg_map as dpgm; print(dpgm.list_providers())"`.
- Ran `uv run python -m py_compile` across all example files.
- Started `examples/basic_map.py` under a 5-second timeout; it launched without terminal errors and was stopped by timeout because the GUI loop blocks.
- Ran `uv sync`.
## Next action
Implement Step 7.
Commit and tag `v0.3.0b1`.

181
README.md
View File

@@ -1,53 +1,176 @@
# dpg-map
`dpg-map` is a Dear PyGui map widget package under rebuild.
`dpg-map` is a Dear PyGui map widget for XYZ raster tiles and geographic overlays.
The Step 6 overlay rendering layer is in place:
The rebuilt beta exposes a stable public import:
```python
import dpg_map as dpgm
```
## Install
Use `uv` for development and dependency management:
```bash
uv sync
uv run pytest
```
From another local project, add this package as an editable dependency:
```bash
uv add --editable ../dpg-map
uv run python -c "import dpg_map as dpgm; print(dpgm.list_providers())"
```
## Basic Map
```python
from typing import Any
import dearpygui.dearpygui as _dpg
import dpg_map as dpgm
dpg: Any = _dpg
dpgm.configure(user_agent="my-app/0.1 contact@example.com")
dpg.create_context()
dpg.create_viewport(title="Map", width=1000, height=700)
with dpg.window(label="Map", width=-1, height=-1):
with dpgm.map_widget(tag="map", center=(47.9029, 1.9093), zoom=15, width=-1, height=-1):
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, label="Vehicle")
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
```
## Sizing
The widget is a Dear PyGui `child_window` containing a measured drawlist. The child keeps the requested Dear PyGui sizing intent while the drawlist uses concrete measured pixels.
Supported sizing modes:
- `width=0` and `height=0` keep Dear PyGui default sizing.
- `width=-1` and `height=-1` fill available space where Dear PyGui supports it.
- Positive dimensions request fixed sizes.
- `autosize_x` and `autosize_y` are passed to the child window.
- Hidden layouts preserve the last non-zero measured size until visible again.
Examples:
```bash
uv run python examples/sizing_window.py
uv run python examples/sizing_child.py
uv run python examples/sizing_table.py
uv run python examples/hidden_tab.py
```
## Live Updates
Runtime overlay updates are safe to call from background threads. They update logical state and enqueue renderer commands; Dear PyGui drawing, texture, handler, and viewport calls stay on the GUI thread.
Live marker update:
```python
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, map_tag="map")
dpgm.update_marker("vehicle", lat=current_lat, lon=current_lon, map_tag="map")
```
Live trajectory update:
```python
dpgm.add_trajectory("track", points=[], map_tag="map")
dpgm.update_trajectory("track", points=tuple(points), map_tag="map")
```
Stress examples:
```bash
uv run python examples/markers_live_thread.py
uv run python examples/trajectory_live_thread.py
```
## Providers
OpenStreetMap is registered as `osm` by default. Custom XYZ providers can be registered and selected at runtime:
```python
provider = dpgm.TileProvider(
name="custom",
url_template="https://example.com/{z}/{x}/{y}.png",
attribution="Tiles (c) Example",
)
dpgm.register_provider(provider)
with dpgm.map_widget(tag="map", center=(47.9029, 1.9093), zoom=15):
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093)
dpgm.update_marker("vehicle", lat=47.9030, lon=1.9094, map_tag="map")
dpgm.set_provider("custom", map_tag="map")
```
Implemented so far:
Provider switching preserves overlays and center, clamps zoom to the new provider range, increments the tile generation, and ignores stale tile results from the previous provider.
- public package exports
- tile provider definitions and registry
- Web Mercator projection helpers
- thread-safe logical map state and map registry
- command queue with coalescing for overlay and view updates
- logical marker, polyline, trajectory, and layer models
- persistent disk cache paths, metadata, scanning, pruning, and clearing
- Dear PyGui `child_window` + measured-size `drawlist` widget shell
- GUI-thread frame pump that drains commands, manages textures, and draws raster tiles
- sizing helpers that preserve the last non-zero size across hidden layouts
- asynchronous tile workers that read disk cache, fetch HTTP, and decode images
- memory cache with visible-tile protection and GUI-thread texture deletion
- measured-rectangle mouse interaction for left-drag panning and wheel zooming
- programmatic view commands and screen/latitude-longitude conversion helpers
- marker, polyline, and trajectory rendering on a draw layer separate from tiles
- background-thread overlay updates that coalesce without resetting center or zoom
Example:
Examples:
```bash
uv run python examples/custom_provider.py
```
## Cache
Tiles use an in-memory cache and a persistent provider-namespaced disk cache.
```python
dpgm.configure(
user_agent="my-app/0.1 contact@example.com",
cache_dir=".tile-cache",
memory_cache_max_tiles=512,
disk_cache_max_bytes=2_000_000_000,
)
stats = dpgm.get_cache_stats(map_tag="map")
dpgm.clear_memory_cache(map_tag="map")
dpgm.clear_disk_cache(provider="osm")
```
`disk_cache_max_bytes=None` disables the disk size limit. Memory cache clears are routed through the renderer command queue so texture deletion happens on the GUI thread. Disk cache clears can target all providers or a single provider namespace.
Cache example:
```bash
uv run python examples/cache_stress.py
```
## OpenStreetMap Usage
The default OpenStreetMap provider requires attribution and should use an application-specific `User-Agent`.
```python
dpgm.configure(user_agent="my-product/1.0 contact@example.com")
```
If no user agent is configured, `dpg-map` emits a runtime warning and falls back to a package user agent. Applications are responsible for displaying provider attribution in accordance with provider terms; the renderer draws the provider attribution text on the map.
## Thread-Safety Contract
Public runtime functions are intended to be callable from non-GUI threads unless explicitly documented otherwise. They acquire map locks briefly, update logical state, and/or enqueue commands.
Thread-safe runtime areas include:
- view updates: `set_center`, `set_zoom`, `set_view`, `fit_bounds`
- overlay updates: `add_marker`, `update_marker`, `update_trajectory`, `delete_overlay`
- layer updates: `add_layer`, `show_layer`, `hide_layer`, `clear_layer`
- provider/cache updates: `set_provider`, `clear_memory_cache`, `clear_disk_cache`
`map_widget(...)` creates Dear PyGui items and must be used on the GUI thread inside an active Dear PyGui context.
## Examples
```bash
uv run python examples/basic_map.py
uv run python examples/sizing_window.py
uv run python examples/sizing_child.py
uv run python examples/sizing_table.py
uv run python examples/hidden_tab.py
uv run python examples/cache_stress.py
uv run python examples/custom_provider.py
uv run python examples/markers_live_thread.py
uv run python examples/trajectory_live_thread.py
```

26
examples/cache_stress.py
View File

@@ -21,15 +21,37 @@ def main() -> None:
dpg.create_context()
dpg.create_viewport(title="dpg-map cache stress", width=1000, height=700)
def clear_memory() -> None:
dpgm.clear_memory_cache(map_tag="cache-map")
def clear_disk() -> None:
dpgm.clear_disk_cache(map_tag="cache-map")
def refresh_stats() -> None:
stats = dpgm.get_cache_stats(map_tag="cache-map")
dpg.set_value(
"cache-stats",
(
f"memory {stats.memory_tiles}/{stats.memory_max_tiles} tiles | "
f"disk {stats.disk_bytes // 1024} KiB | "
f"hits m:{stats.memory_hits} d:{stats.disk_hits}"
),
)
with (
dpg.window(label="Cache Stress", width=-1, height=-1),
dpgm.map_widget(
):
with dpg.group(horizontal=True):
dpg.add_button(label="Clear Memory", callback=clear_memory)
dpg.add_button(label="Clear Disk", callback=clear_disk)
dpg.add_button(label="Stats", callback=refresh_stats)
dpg.add_text("", tag="cache-stats")
with dpgm.map_widget(
tag="cache-map",
center=(47.9029, 1.9093),
zoom=14,
width=-1,
height=-1,
),
):
dpgm.add_marker("start", lat=47.9029, lon=1.9093, label="Orleans")

52
examples/custom_provider.py Normal file
View File

@@ -0,0 +1,52 @@
from typing import Any
import dearpygui.dearpygui as _dpg
import dpg_map as dpgm
dpg: Any = _dpg
def main() -> None:
dpgm.configure(user_agent="dpg-map custom_provider example")
provider = dpgm.TileProvider(
name="carto-light",
url_template="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png",
subdomains=("a", "b", "c", "d"),
attribution="(c) OpenStreetMap contributors (c) CARTO",
file_extension="png",
)
if "carto-light" not in dpgm.list_providers():
dpgm.register_provider(provider)
dpg.create_context()
dpg.create_viewport(title="dpg-map custom provider", width=900, height=600)
def use_osm() -> None:
dpgm.set_provider("osm", map_tag="custom-provider-map")
def use_carto() -> None:
dpgm.set_provider("carto-light", map_tag="custom-provider-map")
with dpg.window(label="Custom Provider", width=-1, height=-1):
with dpg.group(horizontal=True):
dpg.add_button(label="OSM", callback=use_osm)
dpg.add_button(label="Carto", callback=use_carto)
with dpgm.map_widget(
tag="custom-provider-map",
provider="carto-light",
center=(47.9029, 1.9093),
zoom=13,
width=-1,
height=-1,
):
dpgm.add_marker("orleans", lat=47.9029, lon=1.9093, label="Orleans")
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
if __name__ == "__main__":
main()

4
pyproject.toml
View File

@@ -1,7 +1,7 @@
[project]
name = "dpg-map"
version = "0.1.0"
description = "Add your description here"
version = "0.3.0b1"
description = "Dear PyGui map widget for XYZ raster tiles and geographic overlays"
readme = "README.md"
authors = [
{ name = "Hector van der Aa", email = "hector@h3cx.dev" }

2
src/dpg_map/__init__.py
View File

@@ -32,6 +32,7 @@ from .api import (
update_polyline,
update_trajectory,
)
from .cache import CacheStats
from .providers import (
TileProvider,
get_provider,
@@ -42,6 +43,7 @@ from .providers import (
from .widget import map_widget
__all__ = [
"CacheStats",
"TileProvider",
"add_layer",
"add_marker",

127
src/dpg_map/api.py
View File

@@ -10,7 +10,12 @@ from typing import Any
from .cache import CacheStats, clear_disk_cache_path, disk_cache_root, disk_cache_size_bytes
from .commands import CommandKind, MapCommand
from .exceptions import CoordinateError, OverlayNotFoundError
from .exceptions import (
CoordinateError,
InvalidProviderError,
MapNotFoundError,
OverlayNotFoundError,
)
from .interaction import latlon_to_screen_in_state, screen_to_latlon_in_state
from .overlays import LayerState, MarkerOverlay, Overlay, PolylineOverlay, TrajectoryOverlay
from .projection import latlon_to_world
@@ -22,6 +27,7 @@ from .state import (
find_map_for_overlay,
get_config,
get_map_state,
list_map_states,
mark_dirty,
)
from .types import Bounds, LatLon, Point, Tag
@@ -90,6 +96,8 @@ def configure(
overlay_update_policy: str = "coalesce",
debug: bool = False,
) -> None:
"""Configure package-wide defaults used by subsequently created maps."""
configure_state(
user_agent=user_agent,
cache_dir=cache_dir,
@@ -104,20 +112,28 @@ def configure(
def set_center(lat: float, lon: float, *, map_tag: Tag | None = None) -> None:
"""Set a map center without changing its zoom."""
set_view(center=_validate_latlon(lat, lon), map_tag=map_tag)
def get_center(*, map_tag: Tag | None = None) -> LatLon:
"""Return the current logical center of a map."""
state = get_map_state(map_tag)
with state.lock:
return state.center
def set_zoom(zoom: int, *, map_tag: Tag | None = None) -> None:
"""Set a map zoom, clamped to the map/provider zoom range."""
set_view(zoom=zoom, map_tag=map_tag)
def get_zoom(*, map_tag: Tag | None = None) -> int:
"""Return the current logical zoom of a map."""
state = get_map_state(map_tag)
with state.lock:
return state.zoom
@@ -129,6 +145,8 @@ def set_view(
zoom: int | None = None,
map_tag: Tag | None = None,
) -> None:
"""Set map center and/or zoom as one logical view update."""
state = get_map_state(map_tag)
with state.lock:
payload: dict[str, Any] = {}
@@ -145,6 +163,8 @@ def set_view(
def fit_bounds(bounds: Bounds, *, map_tag: Tag | None = None) -> None:
"""Set center and zoom so geographic bounds fit the current draw area."""
(south_west, north_east) = bounds
south, west = _validate_latlon(south_west[0], south_west[1])
north, east = _validate_latlon(north_east[0], north_east[1])
@@ -171,11 +191,15 @@ def fit_bounds(bounds: Bounds, *, map_tag: Tag | None = None) -> None:
def screen_to_latlon(x: float, y: float, *, map_tag: Tag | None = None) -> LatLon:
"""Convert map-local screen coordinates to latitude/longitude."""
state = get_map_state(map_tag)
return screen_to_latlon_in_state(state, float(x), float(y))
def latlon_to_screen(lat: float, lon: float, *, map_tag: Tag | None = None) -> Point:
"""Convert latitude/longitude to map-local screen coordinates."""
lat_value, lon_value = _validate_latlon(lat, lon)
state = get_map_state(map_tag)
return latlon_to_screen_in_state(state, lat_value, lon_value)
@@ -192,6 +216,8 @@ def add_marker(
map_tag: Tag | None = None,
**kwargs: Any,
) -> Tag:
"""Add or replace a marker overlay and return its tag."""
state = get_map_state(map_tag)
color = kwargs.get("color", (255, 80, 80, 255))
radius = float(kwargs.get("radius", 5.0))
@@ -231,6 +257,8 @@ def add_polyline(
map_tag: Tag | None = None,
**kwargs: Any,
) -> Tag:
"""Add or replace a polyline overlay and return its tag."""
state = get_map_state(map_tag)
copied_points = _points_from_inputs(points, lats=lats, lons=lons)
with state.lock:
@@ -264,6 +292,8 @@ def add_trajectory(
map_tag: Tag | None = None,
**kwargs: Any,
) -> Tag:
"""Add or replace a trajectory overlay and return its tag."""
state = get_map_state(map_tag)
copied_points = _points_from_inputs(points, lats=lats, lons=lons)
timestamps = kwargs.get("timestamps")
@@ -303,6 +333,8 @@ def update_marker(
map_tag: Tag | None = None,
**kwargs: Any,
) -> None:
"""Update marker properties without changing the map view."""
state = find_map_for_overlay(tag, map_tag)
with state.lock:
overlay = state.overlays.get(tag)
@@ -335,6 +367,8 @@ def update_polyline(
map_tag: Tag | None = None,
**kwargs: Any,
) -> None:
"""Update polyline properties without changing the map view."""
state = find_map_for_overlay(tag, map_tag)
with state.lock:
overlay = state.overlays.get(tag)
@@ -362,6 +396,8 @@ def update_trajectory(
map_tag: Tag | None = None,
**kwargs: Any,
) -> None:
"""Update trajectory properties without changing the map view."""
state = find_map_for_overlay(tag, map_tag)
with state.lock:
overlay = state.overlays.get(tag)
@@ -386,10 +422,14 @@ def update_trajectory(
def set_marker_position(tag: Tag, lat: float, lon: float, *, map_tag: Tag | None = None) -> None:
"""Set a marker latitude/longitude."""
update_marker(tag, lat=lat, lon=lon, map_tag=map_tag)
def set_marker_label(tag: Tag, label: str, *, map_tag: Tag | None = None) -> None:
"""Set a marker label."""
update_marker(tag, label=label, map_tag=map_tag)
@@ -399,10 +439,14 @@ def set_polyline_points(
*,
map_tag: Tag | None = None,
) -> None:
"""Replace a polyline point sequence."""
update_polyline(tag, points=points, map_tag=map_tag)
def set_overlay_show(tag: Tag, show: bool, *, map_tag: Tag | None = None) -> None:
"""Show or hide an overlay without deleting it."""
state = find_map_for_overlay(tag, map_tag)
with state.lock:
overlay = state.overlays.get(tag)
@@ -415,6 +459,8 @@ def set_overlay_show(tag: Tag, show: bool, *, map_tag: Tag | None = None) -> Non
def delete_overlay(tag: Tag, *, map_tag: Tag | None = None) -> None:
"""Delete an overlay from its map and layer."""
state = find_map_for_overlay(tag, map_tag)
with state.lock:
overlay = state.overlays.pop(tag, None)
@@ -427,16 +473,46 @@ def delete_overlay(tag: Tag, *, map_tag: Tag | None = None) -> None:
_queue(state, CommandKind.DELETE_OVERLAY, {"tag": tag})
def add_layer(name: str, *, show: bool = True, map_tag: Tag | None = None) -> None:
def _cache_target_states(map_tag: Tag | None) -> list[Any]:
if map_tag is not None:
return [get_map_state(map_tag)]
try:
return [get_map_state(None)]
except MapNotFoundError:
return list_map_states()
def add_layer(
name: str,
*,
z_index: int | None = None,
show: bool = True,
map_tag: Tag | None = None,
) -> None:
"""Create or update a logical overlay layer."""
state = get_map_state(map_tag)
with state.lock:
layer = _ensure_layer(state, name, z_index=len(state.layers), show=show)
layer = _ensure_layer(
state,
name,
z_index=len(state.layers) if z_index is None else int(z_index),
show=show,
)
if z_index is not None:
layer.z_index = int(z_index)
layer.show = show
mark_dirty(state, DirtyFlags.OVERLAYS)
_queue(state, CommandKind.ADD_LAYER, {"name": name, "show": show})
_queue(
state,
CommandKind.ADD_LAYER,
{"name": name, "show": show, "z_index": layer.z_index},
)
def show_layer(name: str, *, map_tag: Tag | None = None) -> None:
"""Show all overlays assigned to a layer."""
state = get_map_state(map_tag)
with state.lock:
_ensure_layer(state, name).show = True
@@ -445,6 +521,8 @@ def show_layer(name: str, *, map_tag: Tag | None = None) -> None:
def hide_layer(name: str, *, map_tag: Tag | None = None) -> None:
"""Hide all overlays assigned to a layer."""
state = get_map_state(map_tag)
with state.lock:
_ensure_layer(state, name).show = False
@@ -453,6 +531,8 @@ def hide_layer(name: str, *, map_tag: Tag | None = None) -> None:
def clear_layer(name: str, *, map_tag: Tag | None = None) -> None:
"""Delete all overlays assigned to a layer."""
state = get_map_state(map_tag)
with state.lock:
layer = _ensure_layer(state, name)
@@ -464,6 +544,8 @@ def clear_layer(name: str, *, map_tag: Tag | None = None) -> None:
def clear_map(*, map_tag: Tag | None = None) -> None:
"""Delete all overlays and invalidate map tile resources."""
state = get_map_state(map_tag)
with state.lock:
state.overlays.clear()
@@ -475,36 +557,55 @@ def clear_map(*, map_tag: Tag | None = None) -> None:
def set_provider(provider: str | TileProvider, *, map_tag: Tag | None = None) -> None:
provider_obj = get_provider(provider) if isinstance(provider, str) else provider
"""Switch a map to another tile provider while preserving overlays."""
if isinstance(provider, str):
provider_obj = get_provider(provider)
elif isinstance(provider, TileProvider):
provider_obj = provider
else:
raise InvalidProviderError("provider must be a provider name or TileProvider")
state = get_map_state(map_tag)
with state.lock:
if state.provider == provider_obj:
return
state.provider = provider_obj
state.min_zoom = max(state.min_zoom, provider_obj.min_zoom)
state.max_zoom = min(state.max_zoom, provider_obj.max_zoom)
state.min_zoom = provider_obj.min_zoom
state.max_zoom = provider_obj.max_zoom
state.zoom = max(state.min_zoom, min(state.max_zoom, state.zoom))
state.generation += 1
mark_dirty(state, DirtyFlags.PROVIDER | DirtyFlags.TILES)
mark_dirty(state, DirtyFlags.PROVIDER | DirtyFlags.TILES | DirtyFlags.OVERLAYS)
_queue(state, CommandKind.SET_PROVIDER, {"provider": provider_obj.name})
def clear_memory_cache(*, map_tag: Tag | None = None) -> None:
state = get_map_state(map_tag)
"""Clear decoded in-memory tile data through the renderer command queue."""
for state in _cache_target_states(map_tag):
with state.lock:
state.generation += 1
mark_dirty(state, DirtyFlags.TILES)
_queue(state, CommandKind.CLEAR_MEMORY_CACHE, {})
def clear_disk_cache(*, map_tag: Tag | None = None) -> None:
def clear_disk_cache(provider: str | None = None, *, map_tag: Tag | None = None) -> None:
"""Clear persistent tile cache data globally or for one map/provider."""
if provider is not None:
get_provider(provider)
if map_tag is None:
clear_disk_cache_path(get_config().cache_dir)
clear_disk_cache_path(get_config().cache_dir, provider=provider)
return
state = get_map_state(map_tag)
with state.lock:
state.generation += 1
mark_dirty(state, DirtyFlags.TILES)
_queue(state, CommandKind.CLEAR_DISK_CACHE, {})
_queue(state, CommandKind.CLEAR_DISK_CACHE, {"provider": provider})
def get_cache_stats(*, map_tag: Tag | None = None) -> CacheStats:
"""Return memory and disk cache diagnostics."""
config = get_config()
if map_tag is None:
cache_dir = config.cache_dir
@@ -531,6 +632,8 @@ def get_cache_stats(*, map_tag: Tag | None = None) -> CacheStats:
def get_map_debug_state(*, map_tag: Tag | None = None) -> dict[str, Any]:
"""Return a diagnostic snapshot for a map."""
state = get_map_state(map_tag)
with state.lock:
return {

20
src/dpg_map/cache.py
View File

@@ -225,10 +225,20 @@ def scan_disk_cache(cache_dir: str | Path | None) -> list[DiskCacheEntry]:
return entries
def disk_cache_size_bytes(cache_dir: str | Path | None) -> int:
"""Return total bytes for cached tile files."""
def disk_cache_size_bytes(
cache_dir: str | Path | None,
*,
provider: str | None = None,
) -> int:
"""Return total bytes for cached tile files, optionally scoped to one provider."""
if provider is None:
return sum(entry.metadata.size_bytes for entry in scan_disk_cache(cache_dir))
safe_provider = provider.replace("/", "_")
provider_root = disk_cache_root(cache_dir) / safe_provider
if not provider_root.exists():
return 0
return sum(entry.metadata.size_bytes for entry in scan_disk_cache(provider_root))
def plan_disk_prune(
@@ -277,10 +287,12 @@ def prune_disk_cache(
return planned
def clear_disk_cache_path(cache_dir: str | Path | None) -> None:
"""Remove all persistent tile cache files under a cache root."""
def clear_disk_cache_path(cache_dir: str | Path | None, *, provider: str | None = None) -> None:
"""Remove persistent tile cache files under a cache root."""
root = disk_cache_root(cache_dir)
if provider is not None:
root = root / provider.replace("/", "_")
if not root.exists():
return
try:

7
src/dpg_map/renderer.py
View File

@@ -415,7 +415,7 @@ def drain_renderer_commands(state: MapState) -> list[MapCommand]:
state.dirty |= DirtyFlags.VIEW | DirtyFlags.TILES | DirtyFlags.OVERLAYS
elif command.kind is CommandKind.SET_PROVIDER:
state.tile_manager.clear_memory_cache()
state.dirty |= DirtyFlags.PROVIDER | DirtyFlags.TILES
state.dirty |= DirtyFlags.PROVIDER | DirtyFlags.TILES | DirtyFlags.OVERLAYS
elif command.kind in {
CommandKind.ADD_OVERLAY,
CommandKind.UPDATE_OVERLAY,
@@ -432,7 +432,10 @@ def drain_renderer_commands(state: MapState) -> list[MapCommand]:
state.tile_manager.clear_memory_cache()
state.dirty |= DirtyFlags.TILES
elif command.kind is CommandKind.CLEAR_DISK_CACHE:
state.tile_manager.clear_disk_cache(state.cache_dir)
provider = command.payload.get("provider")
if not isinstance(provider, str):
provider = None
state.tile_manager.clear_disk_cache(state.cache_dir, provider=provider)
state.dirty |= DirtyFlags.TILES
return commands

7
src/dpg_map/state.py
View File

@@ -276,6 +276,13 @@ def resolve_map_tag(map_tag: Tag | None = None) -> Tag:
raise MapNotFoundError("map_tag is required outside a map_widget context")
def list_map_states() -> list[MapState]:
"""Return registered map states as a snapshot."""
with _maps_lock:
return list(_maps.values())
def find_map_for_overlay(tag: Tag, map_tag: Tag | None = None) -> MapState:
"""Find the map containing an overlay, optionally scoped by map tag."""

10
src/dpg_map/tiles.py
View File

@@ -316,7 +316,7 @@ class TileManager:
RuntimeWarning,
stacklevel=3,
)
headers["User-Agent"] = "dpg-map/0.1"
headers["User-Agent"] = "dpg-map/0.3.0b1"
return headers
def _visible_disk_paths(self, cache_dir: str | Path | None) -> list[Path]:
@@ -428,10 +428,12 @@ class TileManager:
self._failed.clear()
return tags
def clear_disk_cache(self, cache_dir: str | Path | None) -> None:
"""Clear the persistent cache root."""
def clear_disk_cache(
self, cache_dir: str | Path | None, *, provider: str | None = None
) -> None:
"""Clear the persistent cache root or one provider namespace."""
clear_disk_cache_path(cache_dir)
clear_disk_cache_path(cache_dir, provider=provider)
def snapshot(self) -> TileManagerSnapshot:
"""Return diagnostic counters."""

22
tests/test_cache.py
View File

@@ -7,6 +7,8 @@ from dpg_map.cache import (
DiskCacheConfig,
DiskCacheMetadata,
MemoryCacheConfig,
clear_disk_cache_path,
disk_cache_size_bytes,
plan_disk_prune,
tile_cache_path,
write_disk_metadata,
@@ -66,3 +68,23 @@ def test_disk_cache_prune_ordering(tmp_path: Path) -> None:
planned = plan_disk_prune(tmp_path, 5, protected_paths={protected})
assert planned == [first, second]
def test_provider_scoped_disk_cache_clear(tmp_path: Path) -> None:
osm = tile_cache_path(tmp_path, "osm", 1, 1, 1)
custom = tile_cache_path(tmp_path, "custom", 1, 1, 1)
for path in (osm, custom):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(b"abcde")
write_disk_metadata(
path.with_suffix(".json"),
DiskCacheMetadata(url=str(path), last_accessed_at=1.0, size_bytes=5),
)
assert disk_cache_size_bytes(tmp_path, provider="osm") == 5
clear_disk_cache_path(tmp_path, provider="osm")
assert not osm.exists()
assert custom.exists()
assert disk_cache_size_bytes(tmp_path) == 5

140
tests/test_hardening.py Normal file
View File

@@ -0,0 +1,140 @@
from __future__ import annotations
from math import nan
import pytest
import dpg_map as dpgm
from dpg_map.commands import CommandKind
from dpg_map.exceptions import (
CoordinateError,
MapNotFoundError,
OverlayNotFoundError,
ProviderNotFoundError,
)
from dpg_map.overlays import TrajectoryOverlay
from dpg_map.providers import TileProvider
from dpg_map.renderer import drain_renderer_commands
from dpg_map.state import DirtyFlags, InteractionState, create_map_state, get_map_state
from dpg_map.tiles import TileID, TileResult, TileStatus
def test_public_callables_have_docstrings() -> None:
for name in dpgm.__all__:
value = getattr(dpgm, name)
if callable(value):
assert value.__doc__, name
def test_unknown_map_raises_public_error() -> None:
with pytest.raises(MapNotFoundError):
dpgm.get_center(map_tag="missing-map")
def test_unknown_overlay_raises_public_error() -> None:
create_map_state(tag="missing-overlay")
with pytest.raises(OverlayNotFoundError):
dpgm.update_marker("vehicle", lat=47.0, lon=2.0, map_tag="missing-overlay")
def test_unknown_provider_raises_public_error() -> None:
create_map_state(tag="missing-provider")
with pytest.raises(ProviderNotFoundError):
dpgm.set_provider("missing-provider-name", map_tag="missing-provider")
def test_invalid_coordinates_raise_public_error() -> None:
create_map_state(tag="invalid-coordinates")
with pytest.raises(CoordinateError):
dpgm.add_marker("bad-lat", lat=91.0, lon=2.0, map_tag="invalid-coordinates")
with pytest.raises(CoordinateError):
dpgm.set_center(nan, 2.0, map_tag="invalid-coordinates")
def test_mismatched_polyline_lat_lon_lengths_raise_public_error() -> None:
create_map_state(tag="mismatched-polyline")
with pytest.raises(CoordinateError):
dpgm.add_polyline("line", lats=[47.0, 47.1], lons=[2.0], map_tag="mismatched-polyline")
def test_empty_trajectory_is_valid_for_live_updates() -> None:
create_map_state(tag="empty-trajectory")
dpgm.add_trajectory("track", points=[], map_tag="empty-trajectory")
state = get_map_state("empty-trajectory")
overlay = state.overlays["track"]
assert isinstance(overlay, TrajectoryOverlay)
assert overlay.points == ()
def test_clear_deleted_overlay_raises_public_error() -> None:
create_map_state(tag="deleted-overlay")
dpgm.add_marker("vehicle", lat=47.0, lon=2.0, map_tag="deleted-overlay")
dpgm.delete_overlay("vehicle", map_tag="deleted-overlay")
with pytest.raises(OverlayNotFoundError):
dpgm.delete_overlay("vehicle", map_tag="deleted-overlay")
def test_provider_switch_ignores_tiles_that_finish_after_switch() -> None:
provider = TileProvider(
name="hardening-switch-provider",
url_template="https://tiles.example.test/{z}/{x}/{y}.png",
min_zoom=0,
max_zoom=4,
)
dpgm.register_provider(provider)
try:
state = create_map_state(tag="provider-switch-loading", zoom=3)
old_tile = TileID("osm", 3, 1, 2)
with state.tile_manager._lock:
state.tile_manager._loading.add(old_tile)
dpgm.set_provider("hardening-switch-provider", map_tag="provider-switch-loading")
state.tile_manager._result_queue.put(
TileResult(
old_tile,
generation=0,
status=TileStatus.READY,
width=1,
height=1,
pixels=(1.0, 1.0, 1.0, 1.0),
source="network",
)
)
commands = drain_renderer_commands(state)
accepted = state.tile_manager.drain_results(
generation=state.generation,
provider_name=state.provider.name,
)
assert [command.kind for command in commands] == [CommandKind.SET_PROVIDER]
assert accepted == []
assert state.tile_manager.snapshot().stale_results == 1
assert state.tile_manager.get_ready_tile(old_tile) is None
finally:
dpgm.unregister_provider("hardening-switch-provider")
def test_overlay_update_preserves_active_drag_model_state() -> None:
create_map_state(tag="update-while-dragging", center=(47.0, 2.0), zoom=9)
dpgm.add_marker("vehicle", lat=47.0, lon=2.0, map_tag="update-while-dragging")
state = get_map_state("update-while-dragging")
state.command_queue.drain()
state.dirty = DirtyFlags.NONE
state.interaction = InteractionState(active_drag=True, last_mouse_position=(20.0, 30.0))
dpgm.update_marker("vehicle", lat=47.1, lon=2.1, map_tag="update-while-dragging")
assert state.interaction.active_drag is True
assert state.interaction.last_mouse_position == (20.0, 30.0)
assert state.center == (47.0, 2.0)
assert state.zoom == 9
assert state.dirty == DirtyFlags.OVERLAYS

11
tests/test_overlays_state.py
View File

@@ -66,6 +66,17 @@ def test_layer_state_tracks_visibility_and_overlay_membership() -> None:
assert "vehicle" not in state.overlays
def test_add_layer_can_update_visibility_and_z_index() -> None:
create_map_state(tag="layer-order")
dpgm.add_layer("fleet", z_index=25, show=False, map_tag="layer-order")
dpgm.add_layer("fleet", z_index=30, show=True, map_tag="layer-order")
state = get_map_state("layer-order")
assert state.layers["fleet"].show is True
assert state.layers["fleet"].z_index == 30
def test_threaded_marker_updates_coalesce_without_touching_view_or_drag_state() -> None:
create_map_state(tag="threaded-marker", center=(47.0, 2.0), zoom=9)
dpgm.add_marker("vehicle", lat=47.0, lon=2.0, map_tag="threaded-marker")

1
tests/test_public_api.py
View File

@@ -6,6 +6,7 @@ def test_package_exports_required_public_api() -> None:
expected = {
"configure",
"CacheStats",
"TileProvider",
"register_provider",
"unregister_provider",

59
tests/test_renderer.py
View File

@@ -4,8 +4,10 @@ from typing import Any
import dpg_map as dpgm
from dpg_map.commands import CommandKind, MapCommand
from dpg_map.providers import TileProvider
from dpg_map.renderer import MapRenderer, drain_renderer_commands
from dpg_map.state import DirtyFlags, create_map_state
from dpg_map.tiles import TileID, TileResult, TileStatus
class FakeDpg:
@@ -115,3 +117,60 @@ def test_overlay_update_drain_sets_only_overlay_dirty() -> None:
drain_renderer_commands(state)
assert state.dirty == DirtyFlags.OVERLAYS
def test_provider_switch_keeps_overlays_and_invalidates_tiles() -> None:
provider = TileProvider(
name="renderer-switch-provider",
url_template="https://tiles.example.test/{z}/{x}/{y}.png",
min_zoom=3,
max_zoom=4,
attribution="Example",
)
dpgm.register_provider(provider)
try:
state = create_map_state(tag="provider-switch", center=(47.0, 2.0), zoom=8)
dpgm.add_marker("vehicle", lat=47.0, lon=2.0, map_tag="provider-switch")
state.command_queue.drain()
state.dirty = DirtyFlags.NONE
tile_id = TileID("osm", 3, 1, 2)
state.tile_manager._result_queue.put(
TileResult(
tile_id,
generation=state.generation,
status=TileStatus.READY,
width=1,
height=1,
pixels=(1.0, 1.0, 1.0, 1.0),
source="disk",
)
)
state.tile_manager.drain_results(generation=state.generation, provider_name="osm")
state.tile_manager.set_texture_tag(tile_id, "old-texture")
dpgm.set_provider("renderer-switch-provider", map_tag="provider-switch")
drain_renderer_commands(state)
assert "vehicle" in state.overlays
assert state.center == (47.0, 2.0)
assert state.zoom == 4
assert state.generation == 1
assert state.provider.name == "renderer-switch-provider"
assert state.dirty & DirtyFlags.PROVIDER
assert state.dirty & DirtyFlags.TILES
assert state.dirty & DirtyFlags.OVERLAYS
assert state.tile_manager.get_ready_tile(tile_id) is None
assert state.tile_manager.take_texture_deletions() == ["old-texture"]
finally:
dpgm.unregister_provider("renderer-switch-provider")
def test_map_scoped_clear_disk_cache_command_keeps_dearpygui_out_of_caller_thread() -> None:
state = create_map_state(tag="clear-disk-command")
state.dirty = DirtyFlags.NONE
dpgm.clear_disk_cache(map_tag="clear-disk-command")
commands = state.command_queue.drain()
assert [command.kind for command in commands] == [CommandKind.CLEAR_DISK_CACHE]
assert state.dirty == DirtyFlags.TILES

2
uv.lock generated
View File

@@ -74,7 +74,7 @@ wheels = [
[[package]]
name = "dpg-map"
version = "0.1.0"
version = "0.3.0b1"
source = { editable = "." }
dependencies = [
{ name = "dearpygui" },