"""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):
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")
# 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