pymapflights 0.2.0__py3-none-any.whl

pymapflights/__init__.py

@@ -0,0 +1,76 @@
+"""Asynchronous Python client for the map.flights API (unofficial)."""
+
+from .client import MapFlights, key_prefix
+from .const import VERSION
+from .exceptions import (
+    MapFlightsAuthError,
+    MapFlightsConnectionError,
+    MapFlightsError,
+    MapFlightsKeyDormantError,
+    MapFlightsNoCurrentFlightError,
+    MapFlightsNotFoundError,
+    MapFlightsNotInTariffError,
+    MapFlightsOutOfAreaError,
+    MapFlightsRateLimitError,
+    MapFlightsTariffError,
+)
+from .models import (
+    AircraftFlights,
+    Airline,
+    AirlinePage,
+    AirportRef,
+    Attribution,
+    DayBoard,
+    DayBoardRow,
+    Delay,
+    FlightDelay,
+    FlightPage,
+    FlightSummary,
+    LiveState,
+    Me,
+    MeKey,
+    MeLimits,
+    MeTariff,
+    MeUsage,
+    NearAircraft,
+    NearResponse,
+    RateLimitInfo,
+)
+
+__version__ = VERSION
+
+__all__ = [
+    "AircraftFlights",
+    "Airline",
+    "AirlinePage",
+    "AirportRef",
+    "Attribution",
+    "DayBoard",
+    "DayBoardRow",
+    "Delay",
+    "FlightDelay",
+    "FlightPage",
+    "FlightSummary",
+    "LiveState",
+    "MapFlights",
+    "MapFlightsAuthError",
+    "MapFlightsConnectionError",
+    "MapFlightsError",
+    "MapFlightsKeyDormantError",
+    "MapFlightsNoCurrentFlightError",
+    "MapFlightsNotFoundError",
+    "MapFlightsNotInTariffError",
+    "MapFlightsOutOfAreaError",
+    "MapFlightsRateLimitError",
+    "MapFlightsTariffError",
+    "Me",
+    "MeKey",
+    "MeLimits",
+    "MeTariff",
+    "MeUsage",
+    "NearAircraft",
+    "NearResponse",
+    "RateLimitInfo",
+    "__version__",
+    "key_prefix",
+]

pymapflights/client.py

@@ -0,0 +1,376 @@
+"""Asynchronous client for the map.flights API."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from contextlib import AbstractAsyncContextManager, nullcontext
+from typing import Any, Literal
+
+from aiohttp import ClientError, ClientResponse, ClientSession, ContentTypeError
+from yarl import URL
+
+from .const import (
+    AIRCRAFT_FLIGHTS_MAX_LIMIT,
+    AIRLINES_MAX_LIMIT,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_USER_AGENT,
+    HEADER_API_KEY,
+    HEADER_ATTRIBUTION,
+    HEADER_RATE_LIMIT,
+    HEADER_RATE_REMAINING,
+    HEADER_RATE_RESET,
+    HEADER_RETRY_AFTER,
+    KEY_PREFIX_LENGTH,
+    NEAR_MAX_LIMIT,
+    NEAR_MAX_RADIUS_KM,
+)
+from .exceptions import (
+    MapFlightsAuthError,
+    MapFlightsConnectionError,
+    MapFlightsError,
+    MapFlightsKeyDormantError,
+    MapFlightsNoCurrentFlightError,
+    MapFlightsNotFoundError,
+    MapFlightsNotInTariffError,
+    MapFlightsOutOfAreaError,
+    MapFlightsRateLimitError,
+    MapFlightsTariffError,
+)
+from .models import (
+    AircraftFlights,
+    AirlinePage,
+    DayBoard,
+    FlightPage,
+    Me,
+    NearResponse,
+    RateLimitInfo,
+)
+from .throttle import SCOPE_LIVE, SCOPE_MINUTE, throttle_for
+
+_NOT_IN_TARIFF = frozenset(
+    {"group_not_in_tariff", "endpoint_not_in_tariff", "format_not_in_tariff"}
+)
+_NO_CURRENT_FLIGHT = frozenset({"no current flight", "unknown flight"})
+
+_AIRPORT_RE = re.compile(r"^[A-Za-z0-9-]{3,8}$")
+_CALLSIGN_RE = re.compile(r"^[A-Za-z0-9-]{2,10}$")
+_HEX_RE = re.compile(r"^[0-9a-fA-F]{6}$")
+
+
+def key_prefix(api_key: str) -> str:
+    """Non-secret prefix of a key (`mf_live_` + 8 hex), as `/me` reports it.
+
+    Unique per key and safe to log or use as an identifier. A new key of the
+    same account has a different prefix.
+    """
+    api_key = api_key.strip()
+    if len(api_key) < KEY_PREFIX_LENGTH:
+        raise ValueError("API key is too short")
+    return api_key[:KEY_PREFIX_LENGTH]
+
+
+def _int_or_none(value: str | int | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _coord(value: float) -> str:
+    """Format a path coordinate; 5 decimals are about 1 m."""
+    return str(round(value, 5))
+
+
+class MapFlights:
+    """Client for the map.flights API.
+
+    The aiohttp session is owned by the caller and never closed here. Rate
+    limits are enforced per key across all clients of the process: live
+    requests (`near`) wait for their 5 s slot, and requests that would break
+    the minute limit or a known 429 block raise a local
+    `MapFlightsRateLimitError` without being sent.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        session: ClientSession,
+        user_agent: str = DEFAULT_USER_AGENT,
+        base_url: str = DEFAULT_BASE_URL,
+        request_timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Initialize the client."""
+        self._api_key = api_key.strip()
+        self._session = session
+        self._user_agent = user_agent
+        self._base_url = URL(base_url)
+        self._request_timeout = request_timeout
+        self._throttle = throttle_for(self._api_key)
+        self.attribution: str | None = None
+        """Full attribution from the last `x-data-attribution` header."""
+        self.live_rate_limit: RateLimitInfo | None = None
+        """Rate-limit headers of the last live response (live-data bucket)."""
+        self.daily_rate_limit: RateLimitInfo | None = None
+        """Rate-limit headers of the last other response (daily quota)."""
+
+    @property
+    def key_prefix(self) -> str:
+        """Prefix of the client's key."""
+        return key_prefix(self._api_key)
+
+    @property
+    def remaining_today(self) -> int | None:
+        """Daily quota left according to the last non-live response."""
+        if self.daily_rate_limit is None:
+            return None
+        return self.daily_rate_limit.remaining
+
+    async def near(
+        self,
+        lat: float,
+        lon: float,
+        radius_km: float,
+        *,
+        limit: int | None = None,
+    ) -> NearResponse:
+        """Aircraft within `radius_km` of a point, nearest first.
+
+        `limit` caps the returned list (API default 50); `total` of the
+        response is the real number of aircraft in the radius. Live group:
+        never counts against the daily quota.
+        """
+        if not -90 <= lat <= 90:  # noqa: PLR2004
+            raise ValueError("lat must be between -90 and 90")
+        if not -180 <= lon <= 180:  # noqa: PLR2004
+            raise ValueError("lon must be between -180 and 180")
+        if not 0 < radius_km <= NEAR_MAX_RADIUS_KM:
+            raise ValueError(f"radius_km must be > 0 and <= {NEAR_MAX_RADIUS_KM}")
+        params: dict[str, str] = {}
+        if limit is not None:
+            if not 1 <= limit <= NEAR_MAX_LIMIT:
+                raise ValueError(f"limit must be between 1 and {NEAR_MAX_LIMIT}")
+            params["limit"] = str(limit)
+
+        data = await self._request(
+            f"/api/v1/near/{_coord(lat)}/{_coord(lon)}/{_coord(radius_km)}",
+            params=params,
+            live=True,
+        )
+        return NearResponse.from_dict(data)
+
+    async def me(self) -> Me:
+        """State of the key: tariff, ceilings and today's usage.
+
+        Experimental. Counts against the daily quota; meant for setup and
+        diagnostics, not for polling.
+        """
+        return Me.from_dict(await self._request("/api/v1/me"))
+
+    async def day_board(
+        self,
+        airport: str,
+        direction: Literal["arr", "dep"],
+        *,
+        day: Literal[-1, 0, 1] = 0,
+    ) -> DayBoard:
+        """Arrivals or departures of an airport for one local day.
+
+        Experimental. `airport` is an ICAO or IATA code; `day` is relative to
+        the airport's local today. Not limited to the key's area.
+        """
+        airport = airport.strip().upper()
+        if not _AIRPORT_RE.match(airport):
+            raise ValueError("airport must be an ICAO or IATA code")
+        if direction not in ("arr", "dep"):
+            raise ValueError("direction must be 'arr' or 'dep'")
+        if day not in (-1, 0, 1):
+            raise ValueError("day must be -1, 0 or 1")
+        data = await self._request(
+            f"/api/v1/airports/{airport}/day-board",
+            params={"dir": direction, "day": str(day)},
+        )
+        return DayBoard.from_dict(data)
+
+    async def flight_by_callsign(self, callsign: str) -> FlightPage:
+        """Return the current flight of an ICAO callsign or IATA flight number.
+
+        Experimental. Raises `MapFlightsNoCurrentFlightError` when there is no
+        current flight; that is a normal state and still counts against the
+        daily quota.
+        """
+        callsign = callsign.replace(" ", "").upper()
+        if not _CALLSIGN_RE.match(callsign):
+            raise ValueError("callsign must be 2 to 10 letters or digits")
+        try:
+            data = await self._request(f"/api/v1/flights/by-callsign/{callsign}")
+        except MapFlightsNotFoundError as err:
+            reason = err.body.get("error")
+            if reason not in _NO_CURRENT_FLIGHT:
+                raise
+            last_flight = err.body.get("lastFlight")
+            raise MapFlightsNoCurrentFlightError(
+                str(err),
+                reason=reason,
+                last_flight=last_flight if isinstance(last_flight, dict) else None,
+                body=err.body,
+            ) from err
+        return FlightPage.from_dict(data)
+
+    async def aircraft_flights(
+        self, hex_id: str, *, limit: int | None = None
+    ) -> AircraftFlights:
+        """Recent flights of an airframe, newest first."""
+        hex_id = hex_id.strip().lower()
+        if not _HEX_RE.match(hex_id):
+            raise ValueError("hex_id must be a 6-digit hex ICAO address")
+        params: dict[str, str] = {}
+        if limit is not None:
+            if not 1 <= limit <= AIRCRAFT_FLIGHTS_MAX_LIMIT:
+                raise ValueError(
+                    f"limit must be between 1 and {AIRCRAFT_FLIGHTS_MAX_LIMIT}"
+                )
+            params["limit"] = str(limit)
+        data = await self._request(f"/api/v1/aircraft/{hex_id}/flights", params=params)
+        return AircraftFlights.from_dict(data)
+
+    async def airlines(
+        self,
+        *,
+        query: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+    ) -> AirlinePage:
+        """One page of the observed airlines (for ICAO code to name)."""
+        params: dict[str, str] = {}
+        if query is not None:
+            params["q"] = query
+        if limit is not None:
+            if not 1 <= limit <= AIRLINES_MAX_LIMIT:
+                raise ValueError(f"limit must be between 1 and {AIRLINES_MAX_LIMIT}")
+            params["limit"] = str(limit)
+        if offset:
+            if offset < 0:
+                raise ValueError("offset must not be negative")
+            params["offset"] = str(offset)
+        return AirlinePage.from_dict(
+            await self._request("/api/v1/airlines", params=params)
+        )
+
+    async def _request(
+        self,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        live: bool = False,
+    ) -> dict[str, Any]:
+        slot: AbstractAsyncContextManager[None]
+        if live:
+            slot = self._throttle.live()
+        else:
+            self._throttle.rest()
+            slot = nullcontext()
+
+        async with slot:
+            try:
+                _, body = await self._get(path, params, live=live)
+            except MapFlightsRateLimitError as err:
+                default = SCOPE_LIVE if live else SCOPE_MINUTE
+                self._throttle.block(err.scope or default, err.retry_after)
+                raise
+
+        if not isinstance(body, dict):
+            raise MapFlightsError("Unexpected response from map.flights")
+        return body
+
+    async def _get(
+        self, path: str, params: dict[str, str] | None, *, live: bool
+    ) -> tuple[ClientResponse, object]:
+        url = self._base_url.with_path(path)
+        headers = {
+            HEADER_API_KEY: self._api_key,
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        try:
+            async with asyncio.timeout(self._request_timeout):
+                response = await self._session.get(url, params=params, headers=headers)
+                async with response:
+                    self._read_headers(response, live=live)
+                    body = await self._json(response)
+        except TimeoutError as err:
+            raise MapFlightsConnectionError(
+                "Timeout while talking to map.flights"
+            ) from err
+        except ClientError as err:
+            raise MapFlightsConnectionError(
+                f"Error while talking to map.flights: {err}"
+            ) from err
+
+        if response.status >= 400:  # noqa: PLR2004
+            raise self._error(response, body)
+        return response, body
+
+    def _read_headers(self, response: ClientResponse, *, live: bool) -> None:
+        if attribution := response.headers.get(HEADER_ATTRIBUTION):
+            self.attribution = attribution
+        if HEADER_RATE_REMAINING not in response.headers:
+            return
+        info = RateLimitInfo(
+            limit=_int_or_none(response.headers.get(HEADER_RATE_LIMIT)),
+            remaining=_int_or_none(response.headers.get(HEADER_RATE_REMAINING)),
+            reset_s=_int_or_none(response.headers.get(HEADER_RATE_RESET)),
+        )
+        if live:
+            self.live_rate_limit = info
+        else:
+            self.daily_rate_limit = info
+
+    @staticmethod
+    async def _json(response: ClientResponse) -> object:
+        try:
+            return await response.json()
+        except (ContentTypeError, ValueError):
+            if response.status < 400:  # noqa: PLR2004
+                raise MapFlightsError("map.flights did not answer with JSON") from None
+            return None
+
+    @staticmethod
+    def _error(  # noqa: PLR0911
+        response: ClientResponse, body: object
+    ) -> MapFlightsError:
+        info: dict[str, Any] = body if isinstance(body, dict) else {}
+        code = info.get("code")
+        message = str(
+            info.get("message") or info.get("error") or f"HTTP {response.status}"
+        )
+
+        if response.status == 401:  # noqa: PLR2004
+            return MapFlightsAuthError(message)
+        if response.status == 403:  # noqa: PLR2004
+            tariff = info.get("tariff")
+            code = str(code or "forbidden")
+            if code == "out_of_area":
+                return MapFlightsOutOfAreaError(message, code=code, tariff=tariff)
+            if code == "key_dormant":
+                return MapFlightsKeyDormantError(message, code=code, tariff=tariff)
+            if code in _NOT_IN_TARIFF:
+                return MapFlightsNotInTariffError(message, code=code, tariff=tariff)
+            return MapFlightsTariffError(message, code=code, tariff=tariff)
+        if response.status == 404:  # noqa: PLR2004
+            return MapFlightsNotFoundError(message, body=info)
+        if response.status == 429:  # noqa: PLR2004
+            retry_after = _int_or_none(response.headers.get(HEADER_RETRY_AFTER))
+            if retry_after is None:
+                retry_after = _int_or_none(info.get("retryAfterS"))
+            return MapFlightsRateLimitError(
+                message,
+                retry_after=retry_after,
+                scope=info.get("scope"),
+                limit=_int_or_none(info.get("limit")),
+            )
+        return MapFlightsError(f"HTTP {response.status}: {message}")

pymapflights/const.py

@@ -0,0 +1,26 @@
+"""Constants for the map.flights API client."""
+
+from typing import Final
+
+VERSION: Final = "0.2.0"
+
+DEFAULT_BASE_URL: Final = "https://map.flights"
+DEFAULT_USER_AGENT: Final = (
+    f"pymapflights/{VERSION} (+https://github.com/olli-dot-dev/pymapflights)"
+)
+DEFAULT_TIMEOUT: Final = 10.0
+
+HEADER_API_KEY: Final = "x-api-key"
+HEADER_ATTRIBUTION: Final = "x-data-attribution"
+HEADER_RETRY_AFTER: Final = "Retry-After"
+HEADER_RATE_LIMIT: Final = "X-RateLimit-Limit"
+HEADER_RATE_REMAINING: Final = "X-RateLimit-Remaining"
+HEADER_RATE_RESET: Final = "X-RateLimit-Reset"
+
+KEY_PREFIX_LENGTH: Final = 16
+"""`mf_live_` + 8 hex."""
+
+NEAR_MAX_RADIUS_KM: Final = 500
+NEAR_MAX_LIMIT: Final = 500
+AIRCRAFT_FLIGHTS_MAX_LIMIT: Final = 50
+AIRLINES_MAX_LIMIT: Final = 200

pymapflights/exceptions.py

@@ -0,0 +1,92 @@
+"""Exceptions raised by the map.flights API client."""
+
+from typing import Any
+
+
+class MapFlightsError(Exception):
+    """Base error of the map.flights client."""
+
+
+class MapFlightsConnectionError(MapFlightsError):
+    """The API could not be reached or did not answer in time."""
+
+
+class MapFlightsAuthError(MapFlightsError):
+    """The API key is unknown or revoked (401 `invalid_key`)."""
+
+
+class MapFlightsNotFoundError(MapFlightsError):
+    """The requested object does not exist (404). Counts against the quota."""
+
+    def __init__(self, message: str, *, body: dict[str, Any] | None = None) -> None:
+        """Initialize with the parsed error body."""
+        super().__init__(message)
+        self.body: dict[str, Any] = body or {}
+
+
+class MapFlightsNoCurrentFlightError(MapFlightsNotFoundError):
+    """No current flight under a callsign (404 of `by-callsign`).
+
+    A normal state when tracking, not a failure. `reason` is `no current flight`
+    (only a flight older than 6 hours exists, see `last_flight`) or
+    `unknown flight` (nobody transmits the callsign and no flight is known).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        reason: str,
+        last_flight: dict[str, Any] | None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize with the reason and the raw last flight (untyped in the spec)."""
+        super().__init__(message, body=body)
+        self.reason = reason
+        self.last_flight = last_flight
+
+
+class MapFlightsTariffError(MapFlightsError):
+    """The key's tariff denies the request (403)."""
+
+    def __init__(self, message: str, *, code: str, tariff: str | None) -> None:
+        """Initialize with the machine-readable code and the key's tariff."""
+        super().__init__(message)
+        self.code = code
+        self.tariff = tariff
+
+
+class MapFlightsOutOfAreaError(MapFlightsTariffError):
+    """The request lies completely outside the key's area (403 `out_of_area`)."""
+
+
+class MapFlightsKeyDormantError(MapFlightsTariffError):
+    """No station of the key's owner sent data for 7 days (403 `key_dormant`)."""
+
+
+class MapFlightsNotInTariffError(MapFlightsTariffError):
+    """The endpoint, its group or the format is not part of the tariff."""
+
+
+class MapFlightsRateLimitError(MapFlightsError):
+    """A rate limit was exceeded (429), or the client refused to exceed it.
+
+    `scope` is `live`, `minute` or `day`. With `local` the request was never
+    sent because the client knows it would be rejected.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None,
+        scope: str | None,
+        limit: int | None,
+        local: bool = False,
+    ) -> None:
+        """Initialize with the wait time and which ceiling was hit."""
+        super().__init__(message)
+        self.local = local
+        self.retry_after = retry_after
+        self.scope = scope
+        self.limit = limit

pymapflights/models.py

@@ -0,0 +1,442 @@
+"""Data models of the map.flights API.
+
+Derived from the OpenAPI specification (`/api/v1/openapi.json`). Unknown fields
+are ignored, because stable operations may gain fields within `/api/v1`.
+Models of experimental operations make every field optional, because those
+operations may change within `/api/v1`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from mashumaro import DataClassDictMixin, field_options
+from mashumaro.types import SerializationStrategy
+
+
+class UnixMillis(SerializationStrategy):
+    """Unix milliseconds (UTC) as an aware datetime."""
+
+    def serialize(self, value: datetime) -> int:
+        """Convert a datetime to Unix milliseconds."""
+        return int(value.timestamp() * 1000)
+
+    def deserialize(self, value: int) -> datetime:
+        """Convert Unix milliseconds to an aware datetime."""
+        return datetime.fromtimestamp(value / 1000, tz=UTC)
+
+
+class _Model(DataClassDictMixin):
+    """Base of all API models: camelCase aliases, timestamps as datetime."""
+
+    class Config:
+        """mashumaro options."""
+
+        serialize_by_alias = True
+        serialization_strategy = {datetime: UnixMillis()}  # noqa: RUF012
+
+
+@dataclass(frozen=True)
+class RateLimitInfo:
+    """`X-RateLimit-*` headers of a response."""
+
+    limit: int | None
+    remaining: int | None
+    reset_s: int | None
+    """Seconds until the ceiling resets (00:00 UTC for the daily quota)."""
+
+
+# --- /near ------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class NearAircraft(_Model):
+    """One aircraft of `GET /near`. Units: ft, kt, degrees, km."""
+
+    hex: str
+    lat: float
+    lon: float
+    alt_baro: int | None = field(metadata=field_options(alias="altBaro"))
+    """Barometric altitude in ft; None = on ground or unknown."""
+    on_ground: bool = field(metadata=field_options(alias="onGround"))
+    gs: float | None
+    """Ground speed in kt."""
+    track: float | None
+    """Track over ground in degrees."""
+    callsign: str | None
+    registration: str | None
+    typecode: str | None
+    """ICAO type code."""
+    airline_icao: str | None = field(metadata=field_options(alias="airlineIcao"))
+    """Airline ICAO derived from the callsign prefix."""
+    category: str | None
+    """ADS-B emitter category A0-D7."""
+    kind: str
+    """airline, cargo, biz, ga, heli, mil, other or ground (may grow)."""
+    emergency: str | None
+    origin: str | None
+    """Origin ICAO from the callsign mapping (candidate, not observed)."""
+    dest: str | None
+    """Destination ICAO from the callsign mapping (candidate, not observed)."""
+    distance_km: float = field(metadata=field_options(alias="distanceKm"))
+    bearing: float
+    """Bearing from the query point in degrees from north."""
+    age_s: int | None = field(default=None, metadata=field_options(alias="ageS"))
+    """Age of the last real observation in seconds, relative to `now`."""
+    estimated: bool = field(default=False, metadata=field_options(alias="est"))
+    """Position is estimated outside coverage."""
+    ground_object: bool = field(default=False, metadata=field_options(alias="gndObj"))
+    """Unknown ground object, not an aircraft."""
+    gs_estimated: bool = field(default=False, metadata=field_options(alias="gsEst"))
+    track_estimated: bool = field(
+        default=False, metadata=field_options(alias="trackEst")
+    )
+
+    @classmethod
+    def __pre_deserialize__(cls, d: dict[str, object]) -> dict[str, object]:
+        """Treat `null` flags as absent (the live diff sends `null` to clear)."""
+        for key in ("est", "gndObj", "gsEst", "trackEst"):
+            if d.get(key) is None:
+                d.pop(key, None)
+        return d
+
+
+@dataclass(frozen=True)
+class NearResponse(_Model):
+    """Response of `GET /near/{lat}/{lon}/{radius}`."""
+
+    now: datetime
+    """Server time of the snapshot."""
+    total: int
+    """Aircraft within the radius in total; `aircraft` is capped by `limit`."""
+    aircraft: list[NearAircraft] = field(metadata=field_options(alias="ac"))
+    """Nearest aircraft first, at most `limit` entries."""
+    data_delay_s: int | None = field(
+        default=None, metadata=field_options(alias="dataDelayS")
+    )
+    """Tariff delays all data by this many seconds; None = live data."""
+    data_delay_ready: bool | None = field(
+        default=None, metadata=field_options(alias="dataDelayReady")
+    )
+
+    @property
+    def ready(self) -> bool:
+        """False while a delay buffer is still filling (`aircraft` is then empty).
+
+        An empty list in that state does not mean there is no traffic.
+        """
+        return self.data_delay_ready is not False
+
+    @property
+    def truncated(self) -> bool:
+        """True when more aircraft are in the radius than were returned."""
+        return self.total > len(self.aircraft)
+
+
+# --- /me (experimental) -------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MeKey(_Model):
+    """The calling key. `label` is internal text and deliberately not mapped."""
+
+    prefix: str
+    tier: str | None = None
+    created: datetime | None = None
+
+
+@dataclass(frozen=True)
+class MeTariff(_Model):
+    """Tariff of the key (announced by the operator, not yet in the spec)."""
+
+    id: str | None = None
+
+
+@dataclass(frozen=True)
+class MeLimits(_Model):
+    """Ceilings of the key."""
+
+    per_minute: int | None = field(
+        default=None, metadata=field_options(alias="perMinute")
+    )
+    per_day: int | None = field(default=None, metadata=field_options(alias="perDay"))
+
+
+@dataclass(frozen=True)
+class MeUsage(_Model):
+    """Today's usage of the key."""
+
+    day: str | None = None
+    """UTC day the counters belong to."""
+    total: int | None = None
+    remaining_day: int | None = field(
+        default=None, metadata=field_options(alias="remainingDay")
+    )
+    reset_s: int | None = field(default=None, metadata=field_options(alias="resetS"))
+    """Seconds until the quota resets (00:00 UTC)."""
+
+
+@dataclass(frozen=True)
+class Me(_Model):
+    """Response of `GET /me`."""
+
+    key: MeKey
+    limits: MeLimits = field(default_factory=MeLimits)
+    usage: MeUsage = field(default_factory=MeUsage)
+    tariff: MeTariff | None = None
+    attribution: str | None = None
+
+    @property
+    def tariff_id(self) -> str | None:
+        """`home` or `feeder`: `tariff.id`, falling back to `key.tier`."""
+        if self.tariff is not None and self.tariff.id:
+            return self.tariff.id
+        return self.key.tier
+
+
+# --- shared ----------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AirportRef(_Model):
+    """Airport as referenced from flights and boards."""
+
+    icao: str
+    iata: str | None = None
+    name: str | None = None
+    municipality: str | None = None
+    country: str | None = None
+    """ISO 3166-1 alpha-2 country code."""
+    lat: float | None = None
+    lon: float | None = None
+
+
+@dataclass(frozen=True)
+class FlightSummary(_Model):
+    """One flight as built from observed positions.
+
+    `takeoff_time` and `landing_time` are measured by map.flights; a landing
+    appears 20 to 35 minutes after touchdown, and only where receivers see the
+    airport down to the ground.
+    """
+
+    id: int | None
+    """Flight id; None while the flight is still being assembled."""
+    hex: str | None = None
+    callsign: str | None = None
+    registration: str | None = None
+    typecode: str | None = None
+    airline_icao: str | None = field(
+        default=None, metadata=field_options(alias="airlineIcao")
+    )
+    origin: AirportRef | None = None
+    dest: AirportRef | None = None
+    first_seen: datetime | None = field(
+        default=None, metadata=field_options(alias="firstSeen")
+    )
+    last_seen: datetime | None = field(
+        default=None, metadata=field_options(alias="lastSeen")
+    )
+    takeoff_time: datetime | None = field(
+        default=None, metadata=field_options(alias="takeoffTime")
+    )
+    landing_time: datetime | None = field(
+        default=None, metadata=field_options(alias="landingTime")
+    )
+    completeness: str | None = None
+    """complete, no_takeoff, no_landing or mid_air_only."""
+    classification: str | None = None
+    diverted: bool = False
+
+
+# --- /aircraft/{hex}/flights ----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AircraftFlights(_Model):
+    """Response of `GET /aircraft/{hex}/flights`, newest first."""
+
+    hex: str
+    flights: list[FlightSummary]
+
+
+# --- /flights/by-callsign (experimental) -----------------------------------------
+
+
+@dataclass(frozen=True)
+class LiveState(_Model):
+    """Live state of the flight in progress. Units: ft, kt, ft/min."""
+
+    hex: str | None = None
+    callsign: str | None = None
+    lat: float | None = None
+    lon: float | None = None
+    alt_baro: int | None = field(default=None, metadata=field_options(alias="altBaro"))
+    on_ground: bool | None = field(
+        default=None, metadata=field_options(alias="onGround")
+    )
+    gs: float | None = None
+    track: float | None = None
+    baro_rate: float | None = field(
+        default=None, metadata=field_options(alias="baroRate")
+    )
+    squawk: str | None = None
+    emergency: str | None = None
+    updated: datetime | None = None
+
+
+@dataclass(frozen=True)
+class Delay(_Model):
+    """Delay of one end of a flight against the plan."""
+
+    band: str | None = None
+    """early, on_time, delayed_15, delayed_30, delayed_60; None = unknown."""
+    minutes: int | None = None
+    """Deviation in minutes, positive = late."""
+    estimated: bool = False
+    """The minute figure is an estimate: show the band, not the number."""
+    basis: str | None = None
+    """schedule (airport feed) or baseline (median of observations)."""
+    sched_time: datetime | None = field(
+        default=None, metadata=field_options(alias="schedTime")
+    )
+    est_time: datetime | None = field(
+        default=None, metadata=field_options(alias="estTime")
+    )
+    actual_time: datetime | None = field(
+        default=None, metadata=field_options(alias="actualTime")
+    )
+    status: str | None = None
+
+
+@dataclass(frozen=True)
+class FlightDelay(_Model):
+    """Departure and arrival delay of a flight."""
+
+    dep: Delay | None = None
+    arr: Delay | None = None
+
+
+@dataclass(frozen=True)
+class FlightPage(_Model):
+    """Response of `GET /flights/by-callsign/{callsign}`."""
+
+    now: datetime | None = None
+    flight: FlightSummary | None = None
+    live: LiveState | None = None
+    """Present only while this flight is the one in progress."""
+    delay: FlightDelay | None = None
+
+
+# --- /airports/{icao}/day-board (experimental) -------------------------------------
+
+
+@dataclass(frozen=True)
+class Attribution(_Model):
+    """Source credit of a board."""
+
+    text: str | None = None
+    url: str | None = None
+
+
+@dataclass(frozen=True)
+class DayBoardRow(_Model):
+    """One row of an airport day board."""
+
+    key: str
+    basis: str | None = None
+    """board (live board), schedule (timetable), usual (learned) or observed."""
+    plan_time: datetime | None = field(
+        default=None, metadata=field_options(alias="planTime")
+    )
+    est_time: datetime | None = field(
+        default=None, metadata=field_options(alias="estTime")
+    )
+    measured_time: datetime | None = field(
+        default=None, metadata=field_options(alias="measuredTime")
+    )
+    """Take-off or landing measured by map.flights, never a board time."""
+    seen_time: datetime | None = field(
+        default=None, metadata=field_options(alias="seenTime")
+    )
+    flight_number: str | None = field(
+        default=None, metadata=field_options(alias="flightNumber")
+    )
+    callsign: str | None = None
+    codeshares: list[str] | None = None
+    airline_icao: str | None = field(
+        default=None, metadata=field_options(alias="airlineIcao")
+    )
+    airline_iata: str | None = field(
+        default=None, metadata=field_options(alias="airlineIata")
+    )
+    airline_name: str | None = field(
+        default=None, metadata=field_options(alias="airlineName")
+    )
+    counterpart: AirportRef | None = None
+    """Origin for arrivals, destination for departures."""
+    gate: str | None = None
+    terminal: str | None = None
+    belt: str | None = None
+    status: str | None = None
+    band: str | None = None
+    """early, on_time, delayed_15, delayed_30, delayed_60; None = unknown."""
+    band_basis: str | None = field(
+        default=None, metadata=field_options(alias="bandBasis")
+    )
+    typecode: str | None = None
+    flight_id: int | None = field(
+        default=None, metadata=field_options(alias="flightId")
+    )
+
+
+@dataclass(frozen=True)
+class DayBoard(_Model):
+    """Response of `GET /airports/{icao}/day-board`."""
+
+    icao: str
+    iata: str | None = None
+    name: str | None = None
+    tz: str | None = None
+    """IANA time zone of the airport."""
+    dir: str | None = None
+    day: int | None = None
+    date: str | None = None
+    """Local date of the day (YYYY-MM-DD)."""
+    from_time: datetime | None = field(
+        default=None, metadata=field_options(alias="from")
+    )
+    to_time: datetime | None = field(default=None, metadata=field_options(alias="to"))
+    generated_at: datetime | None = field(
+        default=None, metadata=field_options(alias="generatedAt")
+    )
+    source: str | None = None
+    """feed, observed or none (nothing known, rows empty)."""
+    rows: list[DayBoardRow] = field(default_factory=list)
+    truncated: bool = False
+    attribution: Attribution | None = None
+    board_fetched: datetime | None = field(
+        default=None, metadata=field_options(alias="boardFetched")
+    )
+
+
+# --- /airlines -----------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Airline(_Model):
+    """One airline of `GET /airlines`."""
+
+    icao: str
+    iata: str | None = None
+    name: str | None = None
+    country: str | None = None
+
+
+@dataclass(frozen=True)
+class AirlinePage(_Model):
+    """One page of `GET /airlines`."""
+
+    total: int
+    items: list[Airline]

pymapflights/throttle.py

@@ -0,0 +1,117 @@
+"""Client-side enforcement of the map.flights rate limits, shared per key.
+
+All clients created with the same key in one process share one `KeyThrottle`,
+so no caller can bypass the live-data interval by creating a second client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections import deque
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Final
+
+from .exceptions import MapFlightsRateLimitError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+LIVE_INTERVAL_S: Final = 5.0
+"""`/live` and `/near`: at most one request every 5 s per key."""
+MINUTE_LIMIT: Final = 60
+"""All endpoints together: at most 60 requests per minute per key."""
+MINUTE_WINDOW_S: Final = 60.0
+
+SCOPE_LIVE: Final = "live"
+SCOPE_MINUTE: Final = "minute"
+SCOPE_DAY: Final = "day"
+
+
+class KeyThrottle:
+    """Rate limits of one API key."""
+
+    def __init__(self) -> None:
+        """Initialize with the limits in force at creation time."""
+        self.live_interval = LIVE_INTERVAL_S
+        self.minute_limit = MINUTE_LIMIT
+        self._lock: asyncio.Lock | None = None
+        self._lock_loop: asyncio.AbstractEventLoop | None = None
+        self._next_live = 0.0
+        self._minute: deque[float] = deque()
+        self._blocked: dict[str, float] = {}
+
+    def _live_lock(self) -> asyncio.Lock:
+        loop = asyncio.get_running_loop()
+        if self._lock is None or self._lock_loop is not loop:
+            self._lock = asyncio.Lock()
+            self._lock_loop = loop
+        return self._lock
+
+    @asynccontextmanager
+    async def live(self) -> AsyncIterator[None]:
+        """Hold the live slot of the key for one request.
+
+        Waits for the next free slot when it is at most one interval away and
+        refuses (local 429) when the key is blocked for longer. The slot is used
+        up whatever the outcome; a `/near` outside the area costs it too.
+        """
+        async with self._live_lock():
+            now = time.monotonic()
+            free_at = max(self._next_live, self._blocked.get(SCOPE_LIVE, 0.0))
+            wait = free_at - now
+            if wait > self.live_interval:
+                raise _local_error(SCOPE_LIVE, wait)
+            if wait > 0:
+                await asyncio.sleep(wait)
+            self._take_minute_slot()
+            try:
+                yield
+            finally:
+                self._next_live = time.monotonic() + self.live_interval
+
+    def rest(self) -> None:
+        """Account for one request to an endpoint outside the live group."""
+        now = time.monotonic()
+        for scope in (SCOPE_DAY, SCOPE_MINUTE):
+            wait = self._blocked.get(scope, 0.0) - now
+            if wait > 0:
+                raise _local_error(scope, wait)
+        self._take_minute_slot()
+
+    def block(self, scope: str, retry_after: int | None) -> None:
+        """Remember a 429 so that further requests are not sent too early."""
+        if retry_after is None or retry_after <= 0:
+            return
+        until = time.monotonic() + retry_after
+        self._blocked[scope] = max(self._blocked.get(scope, 0.0), until)
+
+    def _take_minute_slot(self) -> None:
+        now = time.monotonic()
+        while self._minute and self._minute[0] <= now - MINUTE_WINDOW_S:
+            self._minute.popleft()
+        if len(self._minute) >= self.minute_limit:
+            raise _local_error(SCOPE_MINUTE, self._minute[0] + MINUTE_WINDOW_S - now)
+        self._minute.append(now)
+
+
+def _local_error(scope: str, wait: float) -> MapFlightsRateLimitError:
+    retry_after = max(1, math.ceil(wait))
+    return MapFlightsRateLimitError(
+        f"Rate limit '{scope}' reached, retry in {retry_after} s",
+        retry_after=retry_after,
+        scope=scope,
+        limit=None,
+        local=True,
+    )
+
+
+_throttles: dict[str, KeyThrottle] = {}
+
+
+def throttle_for(api_key: str) -> KeyThrottle:
+    """Return the shared throttle of `api_key`."""
+    if (throttle := _throttles.get(api_key)) is None:
+        throttle = _throttles[api_key] = KeyThrottle()
+    return throttle

pymapflights-0.2.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: pymapflights
+Version: 0.2.0
+Summary: Asynchronous Python client for the map.flights API (unofficial)
+Project-URL: Homepage, https://github.com/olli-dot-dev/pymapflights
+Project-URL: Issues, https://github.com/olli-dot-dev/pymapflights/issues
+Author-email: Olli <1@olli.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ads-b,aircraft,async,flights,home-assistant,map.flights
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: mashumaro>=3.13
+Requires-Dist: yarl>=1.9.0
+Description-Content-Type: text/markdown
+
+# pymapflights
+
+Asynchronous Python client for the [map.flights](https://map.flights) API.
+
+> **Unofficial.** This library is not made or endorsed by map.flights. It is the
+> API layer of the Home Assistant integration
+> [ha-mapflights](https://github.com/olli-dot-dev/ha-mapflights).
+
+## Installation
+
+```bash
+pip install pymapflights
+```
+
+## Usage
+
+```python
+import asyncio
+
+from aiohttp import ClientSession
+
+from pymapflights import MapFlights
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        client = MapFlights(
+            "YOUR_API_KEY",
+            session=session,
+            user_agent="my-app/1.0 (+https://example.com)",
+        )
+        result = await client.near(48.11, 16.57, 25, limit=100)
+        print(f"{result.total} aircraft within 25 km")
+        for aircraft in result.aircraft:
+            print(aircraft.callsign, aircraft.distance_km, aircraft.alt_baro)
+        print(client.attribution)
+
+
+asyncio.run(main())
+```
+
+Notes:
+
+- `total` is the number of aircraft in the radius; `aircraft` is capped by
+  `limit` (API default 50, max 500). `result.truncated` tells you when the list
+  is incomplete.
+- When `result.ready` is `False`, a delayed tariff is still filling its buffer
+  and the empty list does not mean there is no traffic.
+- The session belongs to you; the client never closes it.
+
+## Endpoints
+
+| Method | Endpoint | Stability | Quota |
+|---|---|---|---|
+| `near(lat, lon, radius_km, limit=)` | `/near/{lat}/{lon}/{radius}` | stable | live (1 per 5 s) |
+| `aircraft_flights(hex_id, limit=)` | `/aircraft/{hex}/flights` | stable | daily |
+| `airlines(query=, limit=, offset=)` | `/airlines` | stable | daily |
+| `me()` | `/me` | experimental | daily |
+| `day_board(airport, "arr" \| "dep", day=)` | `/airports/{icao}/day-board` | experimental | daily |
+| `flight_by_callsign(callsign)` | `/flights/by-callsign/{callsign}` | experimental | daily |
+
+Experimental endpoints may change within `/api/v1`; their models make every
+field optional. `key_prefix(api_key)` returns the non-secret key prefix
+(`mf_live_` + 8 hex) without a request.
+
+`flight_by_callsign()` raises `MapFlightsNoCurrentFlightError` when there is
+no current flight (`reason` is `no current flight` with `last_flight`, or
+`unknown flight`). That is a normal state, but it still counts against the
+daily quota. A landing appears there only 20 to 35 minutes after touchdown.
+
+## API keys and terms
+
+Keys are issued by map.flights (operators of a receiving station can create a
+free key at <https://map.flights/account/api-key>). Use of the API is subject to
+the [map.flights API terms](https://map.flights/api-terms). Attribution is
+mandatory: show at least "Data: map.flights"; the full text of the last response
+is in `client.attribution`.
+
+### Rate limits
+
+The client enforces the limits per key, shared by every client in the process
+that uses the same key:
+
+- **Live** (`near`): one request every 5 s. A call waits for its slot. Every
+  call uses the slot, even one that fails (a `near` outside the key's area too).
+- **Minute**: at most 60 requests per minute over all endpoints.
+- **After a 429** the client remembers `Retry-After` for that scope (`live`,
+  `minute` or `day`) and refuses further requests of that scope until then.
+
+A refused request raises `MapFlightsRateLimitError` with `local=True` and is
+never sent. `retry_after` and `scope` are set either way.
+
+`client.live_rate_limit` and `client.daily_rate_limit` hold the
+`X-RateLimit-*` headers of the last live and the last other response. For live
+requests they describe the live bucket, not the daily quota, so
+`client.remaining_today` only comes from non-live responses.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `MapFlightsAuthError` | 401, unknown or revoked key |
+| `MapFlightsOutOfAreaError` | 403 `out_of_area` |
+| `MapFlightsKeyDormantError` | 403 `key_dormant` |
+| `MapFlightsNotInTariffError` | 403 `group_not_in_tariff`, `endpoint_not_in_tariff`, `format_not_in_tariff` |
+| `MapFlightsTariffError` | base class of the 403 errors above, also for unknown codes |
+| `MapFlightsNotFoundError` | 404 (parsed body in `body`) |
+| `MapFlightsNoCurrentFlightError` | 404 of `flight_by_callsign`, a normal state |
+| `MapFlightsRateLimitError` | 429, or refused locally (`local=True`) |
+| `MapFlightsConnectionError` | timeout or network error |
+| `MapFlightsError` | base class of everything above |
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```
+
+## License
+
+MIT

pymapflights-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pymapflights/__init__.py,sha256=sPqkFxZOim2u3VdP-Rqqx-Q2V6AZnzeLEB8zkNGRtNs,1547
+pymapflights/client.py,sha256=Eri3xrtQol1YfdX13_P7PD5Gju2Fwo6PYEPMQFg1Fj4,13660
+pymapflights/const.py,sha256=bhbYa2VB7f9NpP88uEc0ExRwmgqe7Yf9v4hONl9gHtg,755
+pymapflights/exceptions.py,sha256=pf0tj_75PtBu3A_POlvd_7PJV6he1sW6nWGmAOhXTz8,2950
+pymapflights/models.py,sha256=4ZgluIqspYz3OF_JyA2fi9TpNa8yjm-KW01v-0obgK0,14161
+pymapflights/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pymapflights/throttle.py,sha256=clFYUMHMlTjRzClDMMisgqjqApQseXapSxqc-FuE-CM,4087
+pymapflights-0.2.0.dist-info/METADATA,sha256=qmtuam0kzUUxNKmupkSgGT81wdfpac_aiAlvMs3bD2A,5400
+pymapflights-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pymapflights-0.2.0.dist-info/licenses/LICENSE,sha256=lDYZn3ck-coHmrSgc_nApJuASm_uTCffTLQE-iZBhdY,1061
+pymapflights-0.2.0.dist-info/RECORD,,

pymapflights-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pymapflights-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.