termradar 0.3.0__py3-none-any.whl

termradar/__init__.py

@@ -0,0 +1,3 @@
+"""TermRadar - live aircraft radar for your terminal."""
+
+__version__ = "0.3.0"

termradar/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as ``python -m termradar``."""
+
+from termradar.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

termradar/cli.py

@@ -0,0 +1,285 @@
+"""TermRadar command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+from contextlib import suppress
+
+from rich.console import Console
+
+from termradar import __version__
+from termradar.config.storage import (
+    AppConfig,
+    ConfigError,
+    RadarSettings,
+    load_config,
+    save_config,
+    validate_radius_km,
+    validate_refresh_seconds,
+)
+from termradar.core.engine import RadarEngine
+from termradar.core.limits import ENRICHMENT_MAX_BURST, LIVE_REFRESH_DEFAULT_SECONDS
+from termradar.core.location import ensure_location_timezone
+from termradar.core.models import Location
+from termradar.providers.adsbdb import AdsbDbRouteProvider
+from termradar.providers.aircraft import AdsbLolAircraftProvider, OpenSkyAircraftProvider
+from termradar.providers.geocoding import GeocodingError, NominatimGeocodingProvider
+from termradar.providers.routes import CachedRouteProvider
+from termradar.session import RadarSession
+
+_DEFAULT_RADIUS_KM = 15.0
+_DEFAULT_REFRESH_SECONDS = LIVE_REFRESH_DEFAULT_SECONDS
+_DEFAULT_ENRICHMENT_LIMIT = ENRICHMENT_MAX_BURST
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``termradar`` CLI."""
+    args = _parse_args(argv)
+    console = Console()
+
+    try:
+        config = load_config()
+    except ConfigError as exc:
+        console.print(f"[red]Config error:[/red] {exc}")
+        console.print(
+            "Fix your config or run [bold]termradar --refresh 5[/bold] "
+            "or [bold]termradar --reset-location[/bold]."
+        )
+        return 1
+
+    if args.reset_location or config.location is None:
+        config = _run_onboarding(config, console)
+        if config.location is None:
+            console.print("[red]No location configured. Exiting.[/red]")
+            return 1
+
+    location = config.location
+    assert location is not None
+
+    if args.location:
+        override = _resolve_location_override(args.location, console)
+        if override is None:
+            return 1
+        location = override
+
+    location = ensure_location_timezone(location)
+
+    try:
+        radius_km = validate_radius_km(
+            args.radius if args.radius is not None else config.radar.radius_km
+        )
+        refresh_seconds = validate_refresh_seconds(
+            args.refresh if args.refresh is not None else config.radar.refresh_seconds
+        )
+    except ConfigError as exc:
+        console.print(f"[red]{exc}[/red]")
+        return 1
+
+    route_provider = CachedRouteProvider(AdsbDbRouteProvider())
+    aircraft_provider = _create_aircraft_provider(args.aircraft_provider)
+    engine = RadarEngine(
+        aircraft_provider=aircraft_provider,
+        route_provider=route_provider,
+        location=location,
+        radius_km=radius_km,
+        enrichment_limit=args.enrichment_limit,
+    )
+
+    session = RadarSession(engine, refresh_seconds=refresh_seconds)
+    with suppress(KeyboardInterrupt):
+        session.run(console)
+
+    console.print("\n[dim]TermRadar stopped.[/dim]")
+    return 0
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="termradar",
+        description="Live aircraft radar for your terminal.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="See what's flying above you.\n\nMade with <3 Anish",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__} - Made with <3 Anish",
+    )
+    parser.add_argument(
+        "--location",
+        type=str,
+        default=None,
+        metavar="TEXT",
+        help="Temporary radar location override (does not change saved config)",
+    )
+    parser.add_argument(
+        "--radius",
+        "--radius-km",
+        type=float,
+        dest="radius",
+        default=None,
+        metavar="KM",
+        help="Search radius in kilometres for this run only",
+    )
+    parser.add_argument(
+        "--refresh",
+        type=int,
+        default=None,
+        metavar="SECONDS",
+        help="Refresh interval in seconds for this run only (minimum 5)",
+    )
+    parser.add_argument(
+        "--enrichment-limit",
+        type=int,
+        default=_DEFAULT_ENRICHMENT_LIMIT,
+        help="Maximum nearest aircraft to enrich with route data",
+    )
+    parser.add_argument(
+        "--aircraft-provider",
+        choices=("adsblol", "opensky"),
+        default="adsblol",
+        help="Aircraft data source (default: adsblol)",
+    )
+    parser.add_argument(
+        "--reset-location",
+        action="store_true",
+        help="Re-run location onboarding and update saved config",
+    )
+    return parser.parse_args(argv)
+
+
+def _create_aircraft_provider(name: str):
+    if name == "opensky":
+        return OpenSkyAircraftProvider()
+    return AdsbLolAircraftProvider()
+
+
+def _run_onboarding(config: AppConfig, console: Console) -> AppConfig:
+    console.print("[bold cyan]✈ Welcome to TermRadar[/bold cyan]")
+    console.print()
+    console.print("See what's flying above you.")
+    console.print()
+    console.print("Where should we center your radar?")
+    console.print()
+
+    query = _prompt("Location: ").strip()
+    if not query:
+        console.print("[red]Location cannot be empty.[/red]")
+        return config
+
+    console.print("\n[dim]Searching for locations...[/dim]")
+    geocoder = NominatimGeocodingProvider()
+    try:
+        candidates = geocoder.search(query)
+    except GeocodingError as exc:
+        console.print(f"[red]Geocoding failed:[/red] {exc}")
+        return config
+
+    if not candidates:
+        console.print(f"[red]No results found for {query!r}.[/red]")
+        return config
+
+    selected = _choose_candidate(candidates, console)
+    if selected is None:
+        return config
+
+    radius_input = _prompt(f"Search radius [{_DEFAULT_RADIUS_KM:.0f} km]: ").strip()
+    try:
+        radius_km = validate_radius_km(float(radius_input)) if radius_input else _DEFAULT_RADIUS_KM
+    except (ConfigError, ValueError):
+        console.print(f"[yellow]Invalid radius, using {_DEFAULT_RADIUS_KM:.0f} km.[/yellow]")
+        radius_km = _DEFAULT_RADIUS_KM
+
+    refresh_input = _prompt(f"Refresh interval [{_DEFAULT_REFRESH_SECONDS} seconds]: ").strip()
+    try:
+        refresh_seconds = (
+            validate_refresh_seconds(int(refresh_input))
+            if refresh_input
+            else _DEFAULT_REFRESH_SECONDS
+        )
+    except (ConfigError, ValueError):
+        console.print(
+            f"[yellow]Invalid refresh interval, using {_DEFAULT_REFRESH_SECONDS} seconds.[/yellow]"
+        )
+        refresh_seconds = _DEFAULT_REFRESH_SECONDS
+
+    location = ensure_location_timezone(
+        Location(
+            query=query,
+            display_name=selected.display_name,
+            latitude=selected.latitude,
+            longitude=selected.longitude,
+        )
+    )
+
+    config.location = location
+    config.radar = RadarSettings(radius_km=radius_km, refresh_seconds=refresh_seconds)
+    save_config(config)
+    console.print()
+    console.print("[green]Configuration saved.[/green]")
+    console.print()
+    console.print("[bold]Starting radar...[/bold]")
+    console.print()
+    return config
+
+
+def _resolve_location_override(query: str, console: Console) -> Location | None:
+    console.print(f"[dim]Resolving temporary location: {query}[/dim]")
+    geocoder = NominatimGeocodingProvider()
+    try:
+        candidates = geocoder.search(query)
+    except GeocodingError as exc:
+        console.print(f"[red]Geocoding failed:[/red] {exc}")
+        return None
+
+    if not candidates:
+        console.print(f"[red]No results found for {query!r}.[/red]")
+        return None
+
+    if len(candidates) == 1:
+        selected = candidates[0]
+    else:
+        selected = _choose_candidate(candidates, console)
+        if selected is None:
+            return None
+
+    return ensure_location_timezone(
+        Location(
+            query=query,
+            display_name=selected.display_name,
+            latitude=selected.latitude,
+            longitude=selected.longitude,
+        )
+    )
+
+
+def _choose_candidate(candidates: list, console: Console) -> object | None:
+    if len(candidates) == 1:
+        console.print(f"1. {candidates[0].display_name}")
+        choice = _prompt("Choose [1]: ").strip()
+        if choice and choice != "1":
+            console.print("[red]Invalid choice.[/red]")
+            return None
+        return candidates[0]
+
+    for index, candidate in enumerate(candidates, start=1):
+        console.print(f"{index}. {candidate.display_name}")
+
+    while True:
+        choice = _prompt("Choose [1]: ").strip() or "1"
+        try:
+            selected_index = int(choice)
+        except ValueError:
+            console.print("[red]Enter a number.[/red]")
+            continue
+        if 1 <= selected_index <= len(candidates):
+            return candidates[selected_index - 1]
+        console.print(f"[red]Choose between 1 and {len(candidates)}.[/red]")
+
+
+def _prompt(message: str) -> str:
+    try:
+        return input(message)
+    except (EOFError, KeyboardInterrupt):
+        print()
+        raise SystemExit(130) from None

termradar/config/__init__.py

@@ -0,0 +1,23 @@
+"""Configuration management."""
+
+from termradar.config.storage import (
+    AppConfig,
+    ConfigError,
+    RadarSettings,
+    config_path,
+    load_config,
+    save_config,
+    validate_radius_km,
+    validate_refresh_seconds,
+)
+
+__all__ = [
+    "AppConfig",
+    "ConfigError",
+    "RadarSettings",
+    "config_path",
+    "load_config",
+    "save_config",
+    "validate_radius_km",
+    "validate_refresh_seconds",
+]

termradar/config/storage.py

@@ -0,0 +1,207 @@
+"""Configuration loading and persistence."""
+
+from __future__ import annotations
+
+import logging
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import tomli_w
+from platformdirs import user_config_dir
+
+from termradar.core.limits import (
+    LIVE_REFRESH_DEFAULT_SECONDS,
+    LIVE_REFRESH_MAX_SECONDS,
+    LIVE_REFRESH_MIN_SECONDS,
+)
+from termradar.core.location import ensure_location_timezone
+from termradar.core.models import Location
+
+logger = logging.getLogger(__name__)
+
+_APP_NAME = "termradar"
+_DEFAULT_RADIUS_KM = 15.0
+_DEFAULT_REFRESH_SECONDS = LIVE_REFRESH_DEFAULT_SECONDS
+_MIN_RADIUS_KM = 1.0
+_MAX_RADIUS_KM = 250.0
+_MIN_REFRESH_SECONDS = LIVE_REFRESH_MIN_SECONDS
+_MAX_REFRESH_SECONDS = LIVE_REFRESH_MAX_SECONDS
+
+
+class ConfigError(Exception):
+    """Raised when configuration cannot be loaded or validated."""
+
+
+@dataclass(slots=True)
+class RadarSettings:
+    radius_km: float = _DEFAULT_RADIUS_KM
+    refresh_seconds: int = _DEFAULT_REFRESH_SECONDS
+
+
+@dataclass(slots=True)
+class AppConfig:
+    location: Location | None = None
+    radar: RadarSettings = field(default_factory=RadarSettings)
+
+
+def config_path() -> Path:
+    """Return the platform-appropriate config file path."""
+    return Path(user_config_dir(_APP_NAME)) / "config.toml"
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    """Load configuration from disk, returning defaults for a missing file."""
+    path = path or config_path()
+    if not path.exists():
+        return AppConfig()
+
+    try:
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        logger.warning("Could not read config at %s: %s", path, exc)
+        raise ConfigError(f"Corrupted or unreadable config: {path}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError("Config root must be a table")
+
+    location = _parse_location(data.get("location"))
+    radar = _parse_radar(data.get("radar"))
+    config = AppConfig(location=location, radar=radar)
+    _migrate_legacy_refresh(path, data, config)
+    return config
+
+
+def save_config(config: AppConfig, path: Path | None = None) -> None:
+    """Persist configuration to disk."""
+    path = path or config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict = {
+        "radar": {
+            "radius_km": config.radar.radius_km,
+            "refresh_seconds": config.radar.refresh_seconds,
+        }
+    }
+
+    if config.location is not None:
+        data["location"] = {
+            "query": config.location.query,
+            "display_name": config.location.display_name,
+            "latitude": config.location.latitude,
+            "longitude": config.location.longitude,
+        }
+        if config.location.timezone:
+            data["location"]["timezone"] = config.location.timezone
+
+    with path.open("wb") as fh:
+        tomli_w.dump(data, fh)
+
+
+def validate_radius_km(value: float) -> float:
+    """Validate and return a radar search radius in kilometres."""
+    if not (_MIN_RADIUS_KM <= value <= _MAX_RADIUS_KM):
+        raise ConfigError(
+            f"radius_km must be between {_MIN_RADIUS_KM} and {_MAX_RADIUS_KM}, got {value}"
+        )
+    return value
+
+
+def validate_refresh_seconds(value: int) -> int:
+    """Validate and return a refresh interval in seconds."""
+    if value < _MIN_REFRESH_SECONDS:
+        raise ConfigError(f"refresh interval must be at least {_MIN_REFRESH_SECONDS} seconds.")
+    if value > _MAX_REFRESH_SECONDS:
+        raise ConfigError(
+            f"refresh_seconds must be between {_MIN_REFRESH_SECONDS} "
+            f"and {_MAX_REFRESH_SECONDS}, got {value}"
+        )
+    return value
+
+
+def _migrate_legacy_refresh(path: Path, data: dict, config: AppConfig) -> None:
+    """Persist an upgraded refresh interval when an old config used a value below the minimum."""
+    radar_data = data.get("radar")
+    if not isinstance(radar_data, dict) or "refresh_seconds" not in radar_data:
+        return
+    try:
+        saved = int(radar_data["refresh_seconds"])
+    except (TypeError, ValueError):
+        return
+    if saved < _MIN_REFRESH_SECONDS:
+        save_config(config, path)
+
+
+def _parse_location(data: object) -> Location | None:
+    if data is None:
+        return None
+    if not isinstance(data, dict):
+        raise ConfigError("[location] must be a table")
+
+    try:
+        query = str(data["query"])
+        display_name = str(data["display_name"])
+        latitude = float(data["latitude"])
+        longitude = float(data["longitude"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ConfigError("Incomplete [location] section") from exc
+
+    if not (-90.0 <= latitude <= 90.0):
+        raise ConfigError(f"Invalid latitude: {latitude}")
+    if not (-180.0 <= longitude <= 180.0):
+        raise ConfigError(f"Invalid longitude: {longitude}")
+
+    timezone = data.get("timezone")
+    timezone_str = str(timezone).strip() if timezone else None
+
+    location = Location(
+        query=query,
+        display_name=display_name,
+        latitude=latitude,
+        longitude=longitude,
+        timezone=timezone_str,
+    )
+    return ensure_location_timezone(location)
+
+
+def _parse_radar(data: object) -> RadarSettings:
+    if data is None:
+        return RadarSettings()
+    if not isinstance(data, dict):
+        raise ConfigError("[radar] must be a table")
+
+    radius = _DEFAULT_RADIUS_KM
+    refresh = _DEFAULT_REFRESH_SECONDS
+
+    if "radius_km" in data:
+        try:
+            radius = validate_radius_km(float(data["radius_km"]))
+        except (TypeError, ValueError) as exc:
+            raise ConfigError("Invalid radius_km in [radar]") from exc
+
+    if "refresh_seconds" in data:
+        try:
+            refresh = _coerce_refresh_seconds(int(data["refresh_seconds"]))
+        except (TypeError, ValueError) as exc:
+            raise ConfigError("Invalid refresh_seconds in [radar]") from exc
+
+    return RadarSettings(radius_km=radius, refresh_seconds=refresh)
+
+
+def _coerce_refresh_seconds(value: int) -> int:
+    """Load saved refresh values, upgrading legacy intervals below the minimum."""
+    if value < _MIN_REFRESH_SECONDS:
+        logger.warning(
+            "Saved refresh_seconds=%s is below the minimum %s; using %s instead",
+            value,
+            _MIN_REFRESH_SECONDS,
+            _DEFAULT_REFRESH_SECONDS,
+        )
+        return _DEFAULT_REFRESH_SECONDS
+    if value > _MAX_REFRESH_SECONDS:
+        raise ConfigError(
+            f"refresh_seconds must be between {_MIN_REFRESH_SECONDS} "
+            f"and {_MAX_REFRESH_SECONDS}, got {value}"
+        )
+    return value

termradar/core/__init__.py

@@ -0,0 +1,13 @@
+"""Core radar domain logic."""
+
+from termradar.core.engine import RadarEngine
+from termradar.core.models import Aircraft, Location, LocationCandidate, RadarSnapshot, RouteInfo
+
+__all__ = [
+    "Aircraft",
+    "Location",
+    "LocationCandidate",
+    "RadarEngine",
+    "RadarSnapshot",
+    "RouteInfo",
+]

termradar/core/airline.py

@@ -0,0 +1,36 @@
+"""Infer airline identity from flight callsign prefixes."""
+
+from __future__ import annotations
+
+# ICAO three-letter airline prefixes (callsign = prefix + flight number).
+_ICAO_AIRLINES: dict[str, str] = {
+    "AIC": "Air India",
+    "AXB": "Air India Express",
+    "AKJ": "Akasa Air",
+    "IGO": "IndiGo",
+    "SEJ": "SpiceJet",
+    "GOW": "Go First",
+    "VTI": "Vistara",
+    "KAC": "Korean Air",
+    "UAE": "Emirates",
+    "ETD": "Etihad Airways",
+    "QTR": "Qatar Airways",
+    "SIA": "Singapore Airlines",
+    "THY": "Turkish Airlines",
+    "BAW": "British Airways",
+    "DLH": "Lufthansa",
+    "AFR": "Air France",
+    "UAL": "United Airlines",
+    "AAL": "American Airlines",
+    "DAL": "Delta Air Lines",
+}
+
+
+def infer_airline_from_callsign(callsign: str | None) -> str | None:
+    """Return an airline name inferred from the ICAO callsign prefix."""
+    if not callsign or not callsign.strip():
+        return None
+    prefix = callsign.strip().upper()[:3]
+    if len(prefix) < 3 or not prefix.isalnum():
+        return None
+    return _ICAO_AIRLINES.get(prefix)

termradar/core/bearing.py

@@ -0,0 +1,25 @@
+"""Initial bearing calculations."""
+
+from __future__ import annotations
+
+import math
+
+
+def bearing_deg(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+) -> float:
+    """Return the initial bearing from point 1 to point 2 in degrees (0–360).
+
+    Convention: 0° North, 90° East, 180° South, 270° West.
+    """
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    d_lambda = math.radians(lon2 - lon1)
+
+    x = math.sin(d_lambda) * math.cos(phi2)
+    y = math.cos(phi1) * math.sin(phi2) - math.sin(phi1) * math.cos(phi2) * math.cos(d_lambda)
+    theta = math.degrees(math.atan2(x, y))
+    return (theta + 360.0) % 360.0

termradar/core/distance.py

@@ -0,0 +1,24 @@
+"""Great-circle distance calculations."""
+
+from __future__ import annotations
+
+import math
+
+_EARTH_RADIUS_KM = 6371.0
+
+
+def distance_km(
+    lat1: float,
+    lon1: float,
+    lat2: float,
+    lon2: float,
+) -> float:
+    """Return the Haversine distance between two WGS-84 points in kilometres."""
+    phi1 = math.radians(lat1)
+    phi2 = math.radians(lat2)
+    d_phi = math.radians(lat2 - lat1)
+    d_lambda = math.radians(lon2 - lon1)
+
+    a = math.sin(d_phi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(d_lambda / 2) ** 2
+    c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+    return _EARTH_RADIUS_KM * c