progress.py

"""Optional progress callbacks for the fetch/render pipeline.

The CLI prints and uses tqdm; the Studio server needs structured stages it can
stream over SSE. Both paths call emit(), which is a no-op when progress is None,
so the CLI is unaffected. Callbacks may be invoked from worker threads (the OSM
fetch pool runs two), so implementations must be thread-safe.

Event names are normative -- see the design spec:
    geocode_start, geocode_done{cached, lat, lon}, fetch_start,
    fetch_layer_done{layer, cached, ok, error}, render_start{edge_count},
    save_start, done, error

Nothing in this module emits `done` or `error`: the two terminal events belong
to the Studio server, which owns their payloads because only it knows the §5
wording and which panel field a failure attaches to. As shipped in ui/session.py:
    done{kind, ...}          kind is "load" | "layers" | "export"; a load also
                             carries label, partial and edge_count
    error{kind, title, body} kind is "geocode" | "offline" | "throttled" |
                             "generic", plus an optional `field` (the panel input
                             to redden) and an optional `detail` (the raw cause).
There is no `message` key -- the UI bolds `title` and runs `body` after it.
"""

import sys
from typing import Callable, Optional

ProgressFn = Callable[[str, dict], None]


def emit(progress: Optional[ProgressFn], event: str, **payload) -> None:
    """
    Deliver one progress event, or do nothing when no callback is installed.

    Telemetry never aborts the work it reports on. A Studio client that closes
    the tab mid-render leaves an SSE queue whose put() raises, and that must not
    take the half-drawn figure down with it, so callback failures are swallowed
    with a one-line note on stderr.
    """
    if progress is None:
        return
    try:
        progress(event, payload)
    except Exception as exc:  # deliberately broad -- see docstring
        print(f"⚠ progress callback failed for '{event}': {exc}", file=sys.stderr)