Source code for openworld_radio_twin.providers.registry

"""Trusted, installed data sources shared by library, batch and HTTP APIs.

One registry type serves every kind of source (buildings, antennas). A source is an
adapter with an identifier, a version, a coverage predicate and attribution. Requests
select a source explicitly or by location; installed packages add sources through the
entry-point group of their kind.
"""

from __future__ import annotations

import json
import re
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from functools import cache, partial
from importlib.metadata import entry_points
from importlib.resources import files
from typing import ClassVar, Protocol

import httpx
from shapely.geometry import Point, shape
from shapely.ops import unary_union
from shapely.prepared import prep

from openworld_radio_twin.config import Settings
from openworld_radio_twin.providers.base import BuildingQueryResult

BUILDING_ENTRY_POINT_GROUP = "openworld_radio_twin.building_sources"
ANTENNA_ENTRY_POINT_GROUP = "openworld_radio_twin.antenna_sources"
# Kept for plugins written against the building-only registry.
ENTRY_POINT_GROUP = BUILDING_ENTRY_POINT_GROUP
RESERVED_IDENTIFIERS = frozenset({"auto", "global", "none"})


[docs] class BuildingProvider(Protocol):
[docs] async def buildings(
self, latitude: float, longitude: float, radius_m: float, limit: int, ) -> BuildingQueryResult: ...
[docs] def worldwide(latitude: float, longitude: float) -> bool: return -90 <= latitude <= 90 and -180 <= longitude <= 180
@cache def _region_boundary(name: str): document = json.loads( files("openworld_radio_twin.providers").joinpath(f"data/{name}.geojson").read_text() ) features = document["features"] if not features: raise ValueError(f"Packaged {name} routing boundary is empty") polygons = [shape(feature["geometry"]) for feature in features] if any(not polygon.is_valid for polygon in polygons): raise ValueError(f"Packaged {name} routing boundary contains invalid polygons") boundary = unary_union(polygons) if ( boundary.is_empty or not boundary.is_valid or boundary.geom_type not in {"Polygon", "MultiPolygon"} ): raise ValueError(f"Packaged {name} routing boundary is invalid") return boundary.bounds, prep(boundary) def _in_region(name: str, latitude: float, longitude: float) -> bool: if not worldwide(latitude, longitude): return False (west, south, east, north), boundary = _region_boundary(name) return ( west <= longitude <= east and south <= latitude <= north and boundary.covers(Point(longitude, latitude)) )
[docs] def region(name: str) -> Callable[[float, float], bool]: """Coverage test for the packaged boundary ``providers/data/<name>.geojson``. The file's provenance is recorded in ``providers/data/README.md``. """ if not files("openworld_radio_twin.providers").joinpath(f"data/{name}.geojson").is_file(): raise ValueError(f"No packaged routing boundary named {name!r}") return partial(_in_region, name)
[docs] @dataclass(frozen=True) class DataSource: """Provider identity and factory; auto-selection is explicitly opt-in. ``covers(latitude, longitude)`` restricts explicit and automatic selection; ``auto_covers`` restricts only automatic selection. Use ``covers`` when the provider cannot tell that a query lies outside its data, such as a live query or a snapshot, and ``auto_covers`` when the provider checks its own tile index and can serve explicit requests beyond the routing boundary. Higher ``auto_priority`` wins; None leaves a source available only by explicit selection. Version changes must accompany changes in source interpretation or geometry reconstruction. ``configured`` reports whether the settings supply what the source needs, such as a token or a local file; automatic routing skips a source that is not configured, and ``configuration_hint`` tells the user how to configure it. """ identifier: str title: str version: str factory: Callable[[Settings, httpx.AsyncClient], object] covers: Callable[[float, float], bool] = worldwide auto_priority: int | None = None attribution: str = "" license_url: str = "" configuration_identity: Callable[[Settings], dict[str, str]] | None = None auto_covers: Callable[[float, float], bool] | None = None configured: Callable[[Settings], bool] | None = None configuration_hint: str = "" license: str = "" def __post_init__(self): if not re.fullmatch(r"[a-z][a-z0-9_-]*|3dbag", self.identifier): raise ValueError("Source identifiers must be lowercase slugs") if self.identifier in RESERVED_IDENTIFIERS: raise ValueError(f"Reserved source identifier: {self.identifier}") if not self.version: raise ValueError("A source requires an implementation version")
[docs] def is_configured(self, settings: Settings) -> bool: return self.configured is None or bool(self.configured(settings))
# Building plugins construct sources under this name. BuildingSource = DataSource
[docs] class SourceRegistry: """Installed sources of one kind; subclasses name the kind and its entry-point group.""" kind: ClassVar[str] = "data" entry_point_group: ClassVar[str | None] = None def __init__(self, sources: tuple[DataSource, ...] = ()) -> None: self._sources: dict[str, DataSource] = {} for source in sources: self.register(source)
[docs] def register(self, source: DataSource) -> None: if not isinstance(source, DataSource): raise TypeError(f"{self.kind.capitalize()} source plugins must return a DataSource") if source.identifier in self._sources: raise ValueError(f"Duplicate {self.kind} source: {source.identifier}") self._sources[source.identifier] = source
[docs] def load_installed(self) -> None: """Load explicitly installed entry points, never a request-supplied import path.""" if self.entry_point_group is None: return for entry in sorted( entry_points(group=self.entry_point_group), key=lambda item: item.name ): source = entry.load()() if source.identifier != entry.name: raise ValueError( f"{self.kind.capitalize()} source entry-point name must match its identifier" ) self.register(source)
[docs] def get(self, identifier: str) -> DataSource: try: return self._sources[identifier] except KeyError: raise ValueError(f"Unknown {self.kind} source: {identifier}") from None
[docs] def automatic( self, latitude: float, longitude: float, *, allowed: tuple[str, ...], settings: Settings | None = None, ) -> DataSource | None: for identifier in allowed: self.get(identifier) # Report misspelled policy instead of changing the source. candidates = [ source for source in self._sources.values() if source.identifier in allowed and source.auto_priority is not None and (settings is None or source.is_configured(settings)) and source.covers(latitude, longitude) and (source.auto_covers is None or source.auto_covers(latitude, longitude)) ] return max( candidates, key=lambda source: (source.auto_priority, source.identifier), default=None )
[docs] def describe(self, settings: Settings | None = None) -> list[dict[str, object]]: return [ { "id": source.identifier, "title": source.title, "version": source.version, "automatic": source.auto_priority is not None, "configured": settings is None or source.is_configured(settings), "configuration_hint": source.configuration_hint, "attribution": source.attribution, "license": source.license, "license_url": source.license_url, } for source in self._sources.values() ]
[docs] class BuildingSourceRegistry(SourceRegistry): kind = "building" entry_point_group = BUILDING_ENTRY_POINT_GROUP
[docs] class AntennaSourceRegistry(SourceRegistry): kind = "antenna" entry_point_group = ANTENNA_ENTRY_POINT_GROUP
[docs] def resolve_source( registry: SourceRegistry, requested: str, latitude: float, longitude: float, settings: Settings, *, allowed: tuple[str, ...], fallback: str, reserved: Mapping[str, str], ) -> dict[str, object]: """Resolve a source before acquisition; explicit selections never fall back silently. ``reserved`` maps the identifiers the caller implements itself (``global``, ``none``) to their versions; ``fallback`` is what ``auto`` becomes when no source applies. """ resolved = requested source: DataSource | None = None if requested == "auto": source = registry.automatic(latitude, longitude, allowed=allowed, settings=settings) resolved = source.identifier if source is not None else fallback if resolved in reserved: source = None version = reserved[resolved] else: source = registry.get(resolved) label = f"{registry.kind.capitalize()} source '{resolved}'" if not source.covers(latitude, longitude): raise ValueError(f"{label} does not cover the query centre") if not source.is_configured(settings): hint = f": {source.configuration_hint}" if source.configuration_hint else "" raise ValueError(f"{label} is not configured{hint}") version = source.version identity: dict[str, object] = { "requested": requested, "resolved": resolved, "implementation_version": version, } if source is not None and source.configuration_identity is not None: identity["configuration"] = source.configuration_identity(settings) return identity