bom-weather-api 0.1.0__py3-none-any.whl

bom_weather_api/__init__.py

@@ -0,0 +1,64 @@
+"""Async client for Australian Bureau of Meteorology weather data."""
+
+from ._version import __version__
+from .client import BomClient
+from .const import ICON_DESCRIPTORS
+from .exceptions import (
+    BomConnectionError,
+    BomError,
+    BomNotFoundError,
+    BomParseError,
+    BomRateLimitError,
+    BomResponseError,
+    BomTimeoutError,
+)
+from .ftp import FileTransport, FtpTransport
+from .geohash import geohash_encode
+from .models import (
+    Coordinate,
+    DailyForecast,
+    DailyForecastDay,
+    ForecastLocation,
+    HourlyForecast,
+    HourlyForecastPoint,
+    NowForecast,
+    Observation,
+    Station,
+    WarningDetails,
+    WeatherWarning,
+    bearing_to_compass,
+    compass_to_bearing,
+    icon_descriptor,
+    strip_html,
+)
+
+__all__ = [
+    "ICON_DESCRIPTORS",
+    "BomClient",
+    "BomConnectionError",
+    "BomError",
+    "BomNotFoundError",
+    "BomParseError",
+    "BomRateLimitError",
+    "BomResponseError",
+    "BomTimeoutError",
+    "Coordinate",
+    "DailyForecast",
+    "DailyForecastDay",
+    "FileTransport",
+    "ForecastLocation",
+    "FtpTransport",
+    "HourlyForecast",
+    "HourlyForecastPoint",
+    "NowForecast",
+    "Observation",
+    "Station",
+    "WarningDetails",
+    "WeatherWarning",
+    "__version__",
+    "bearing_to_compass",
+    "compass_to_bearing",
+    "geohash_encode",
+    "icon_descriptor",
+    "strip_html",
+]

bom_weather_api/_version.py

@@ -0,0 +1,3 @@
+"""Version of bom-weather-api."""
+
+__version__ = "0.1.0"

bom_weather_api/client.py

@@ -0,0 +1,293 @@
+"""Async client for Bureau of Meteorology weather data.
+
+Daily forecasts, observations and forecast locations come from the BoM's
+official anonymous FTP products. Hourly forecasts, warnings and forecast
+extras (extended text, UV, fire danger, sun times) come from the JSON API
+that backs the BoM app.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import replace
+from functools import partial
+import logging
+from typing import TYPE_CHECKING, Any, Self
+
+import aiohttp
+
+from .const import (
+    DEFAULT_TIMEOUT,
+    DEFAULT_USER_AGENT,
+    FTP_FORECAST_DIR,
+    FTP_LOCATIONS_PATH,
+    LEGACY_BASE_URL,
+    PRECIS_PRODUCTS,
+    STATE_PREFIXES,
+)
+from .exceptions import (
+    BomConnectionError,
+    BomError,
+    BomNotFoundError,
+    BomParseError,
+    BomRateLimitError,
+    BomResponseError,
+    BomTimeoutError,
+)
+from .ftp import FileTransport, FtpTransport
+from .models import (
+    Coordinate,
+    DailyForecast,
+    ForecastLocation,
+    HourlyForecast,
+    Observation,
+    Station,
+    WarningDetails,
+    WeatherWarning,
+)
+from .parsers import (
+    merge_legacy_daily,
+    parse_legacy_hourly,
+    parse_legacy_warning,
+    parse_legacy_warnings,
+    parse_locations,
+    parse_observation,
+    parse_precis,
+    parse_stations,
+)
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _state_prefix(state: str) -> str:
+    try:
+        return STATE_PREFIXES[state.upper()]
+    except KeyError as err:
+        raise ValueError(f"Unknown state: {state}") from err
+
+
+class BomClient:
+    """Client for Bureau of Meteorology weather data."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        transport: FileTransport | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: str = DEFAULT_USER_AGENT,
+        legacy_base_url: str = LEGACY_BASE_URL,
+    ) -> None:
+        """Initialise the client.
+
+        Pass an existing ``aiohttp.ClientSession`` to share connections; it is
+        never closed by the client.
+        """
+        self._session = session
+        self._owns_session = session is None
+        self._transport = transport or FtpTransport(timeout=timeout)
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._headers = {"User-Agent": user_agent, "Accept": "application/json"}
+        self._legacy_base_url = legacy_base_url.rstrip("/")
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the session if the client created it."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP session if it is owned by the client."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    # --- Transport helpers -------------------------------------------------
+
+    async def _ftp[T](self, path: str, parser: Callable[[bytes], T]) -> T:
+        """Download an FTP product and parse it in a worker thread."""
+        content = await self._transport.fetch(path)
+        return await asyncio.to_thread(_parse, lambda: parser(content))
+
+    async def _legacy(self, path: str) -> Mapping[str, Any]:
+        """GET a BoM app API path and return the decoded JSON object."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+        try:
+            async with self._session.get(
+                f"{self._legacy_base_url}{path}",
+                headers=self._headers,
+                timeout=self._timeout,
+            ) as response:
+                if response.status == 404:
+                    raise BomNotFoundError(f"Not found: {path}", status=404)
+                if response.status == 429:
+                    raise BomRateLimitError(
+                        "Rate limited by the BoM API",
+                        status=429,
+                        retry_after=_retry_after(response.headers),
+                    )
+                if response.status >= 400:
+                    raise BomResponseError(
+                        f"Unexpected status {response.status} for {path}",
+                        status=response.status,
+                    )
+                try:
+                    data = await response.json(content_type=None)
+                except ValueError as err:
+                    raise BomParseError(f"Invalid JSON returned for {path}") from err
+        except TimeoutError as err:
+            raise BomTimeoutError(f"Timeout requesting {path}") from err
+        except aiohttp.ClientError as err:
+            raise BomConnectionError(f"Error requesting {path}: {err}") from err
+        if not isinstance(data, Mapping):
+            raise BomParseError(f"Unexpected response for {path}")
+        return data
+
+    # --- Locations and stations --------------------------------------------
+
+    async def get_forecast_locations(self) -> list[ForecastLocation]:
+        """Return every town BoM issues a précis forecast for (~860 places)."""
+        return await self._ftp(FTP_LOCATIONS_PATH, parse_locations)
+
+    async def get_stations(self, state: str) -> list[Station]:
+        """Return the observation stations reporting in a state.
+
+        ``state`` is an AAC prefix (``NSW``, ``VIC``, ``QLD``, ``SA``, ``WA``,
+        ``TAS`` or ``NT``); ACT stations are included in ``NSW``.
+        """
+        product = f"ID{_state_prefix(state)}60920.xml"
+        return await self._ftp(
+            f"{FTP_FORECAST_DIR}/{product}",
+            partial(parse_stations, state=state.upper()),
+        )
+
+    @staticmethod
+    def nearest(
+        coordinate: Coordinate,
+        items: Iterable[Any],
+        *,
+        limit: int | None = None,
+    ) -> list[tuple[Any, float]]:
+        """Sort locations or stations by distance (km) from a coordinate."""
+        ranked = sorted(
+            (
+                (item, round(coordinate.distance_to(item.coordinate), 1))
+                for item in items
+                if item.coordinate is not None
+            ),
+            key=lambda pair: pair[1],
+        )
+        return ranked[:limit] if limit is not None else ranked
+
+    # --- Observations ------------------------------------------------------
+
+    async def get_observation(self, state: str, station_id: str) -> Observation:
+        """Return the latest observation for a station."""
+        product = f"ID{_state_prefix(state)}60920.xml"
+        observation = await self._ftp(
+            f"{FTP_FORECAST_DIR}/{product}",
+            partial(parse_observation, station_id=station_id),
+        )
+        if observation is None:
+            raise BomNotFoundError(f"Station {station_id} is not reporting", status=404)
+        return observation
+
+    # --- Forecasts ---------------------------------------------------------
+
+    async def get_daily_forecast(
+        self, location: ForecastLocation, *, extras: bool = True
+    ) -> DailyForecast:
+        """Return the daily town forecast for a location.
+
+        With ``extras=True`` the forecast is enriched with extended text, UV,
+        fire danger and sun times from the BoM app API. If that request fails
+        the base forecast is still returned.
+        """
+        product = PRECIS_PRODUCTS[location.product_state]
+        forecast_task = self._ftp(
+            f"{FTP_FORECAST_DIR}/{product}.xml",
+            partial(parse_precis, aac=location.aac),
+        )
+        if not extras:
+            return await forecast_task
+        forecast: DailyForecast | BaseException
+        legacy: Mapping[str, Any] | BaseException
+        forecast, legacy = await asyncio.gather(
+            forecast_task,
+            self._legacy(f"/locations/{location.coordinate.geohash}/forecasts/daily"),
+            return_exceptions=True,
+        )
+        if isinstance(forecast, BaseException):
+            raise forecast
+        if isinstance(legacy, BomError):
+            _LOGGER.debug("Forecast extras unavailable: %s", legacy)
+            return forecast
+        if isinstance(legacy, BaseException):
+            raise legacy
+        return merge_legacy_daily(forecast, legacy)
+
+    async def get_hourly_forecast(self, coordinate: Coordinate) -> HourlyForecast:
+        """Return the hourly forecast for a coordinate (BoM app API)."""
+        data = await self._legacy(f"/locations/{coordinate.geohash}/forecasts/hourly")
+        return _parse(lambda: parse_legacy_hourly(data))
+
+    # --- Warnings ----------------------------------------------------------
+
+    async def get_warnings(
+        self, coordinate: Coordinate, *, details: bool = False
+    ) -> list[WeatherWarning]:
+        """Return current warnings for a coordinate (BoM app API).
+
+        Cancellations are excluded. With ``details=True`` the plain-text
+        message of each warning is fetched as well.
+        """
+        data = await self._legacy(f"/locations/{coordinate.geohash}/warnings")
+        warnings = _parse(lambda: parse_legacy_warnings(data))
+        if not details or not warnings:
+            return warnings
+        results = await asyncio.gather(
+            *(self.get_warning(warning.id) for warning in warnings),
+            return_exceptions=True,
+        )
+        enriched: list[WeatherWarning] = []
+        for warning, result in zip(warnings, results, strict=True):
+            if isinstance(result, BaseException) and not isinstance(result, BomError):
+                raise result
+            enriched.append(
+                replace(warning, message=result.message)
+                if isinstance(result, WarningDetails)
+                else warning
+            )
+        return enriched
+
+    async def get_warning(self, warning_id: str) -> WarningDetails:
+        """Return the full text of a warning (BoM app API)."""
+        data = await self._legacy(f"/warnings/{warning_id}")
+        return _parse(lambda: parse_legacy_warning(data))
+
+
+def _retry_after(headers: Mapping[str, str]) -> int | None:
+    try:
+        return int(headers["Retry-After"])
+    except (KeyError, ValueError):
+        return None
+
+
+def _parse[T](builder: Callable[[], T]) -> T:
+    """Run a parser, converting unexpected response shapes to BomParseError."""
+    try:
+        return builder()
+    except (KeyError, TypeError, AttributeError, ValueError) as err:
+        raise BomParseError(f"Unexpected response format: {err}") from err

bom_weather_api/const.py

@@ -0,0 +1,84 @@
+"""Constants for the Bureau of Meteorology API client."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from ._version import __version__
+
+# Official anonymous FTP products ("free to access and are not for commercial
+# use", see https://www.bom.gov.au/catalogue/data-feeds.shtml).
+FTP_HOST: Final = "ftp.bom.gov.au"
+FTP_FORECAST_DIR: Final = "/anon/gen/fwo"
+FTP_LOCATIONS_PATH: Final = "/anon/home/adfd/spatial/IDM00013.dbf"
+
+# Undocumented JSON API that backs the BoM app (hourly forecasts and warnings).
+LEGACY_BASE_URL: Final = "https://api.weather.bom.gov.au/v1"
+
+DEFAULT_TIMEOUT: Final = 30.0
+DEFAULT_USER_AGENT: Final = (
+    f"bom-weather-api/{__version__} (+https://github.com/tinkerologie/bom-weather-api)"
+)
+
+# AAC prefix -> state product identifier prefix. ACT locations use NSW codes.
+STATE_PREFIXES: Final[dict[str, str]] = {
+    "NSW": "N",
+    "VIC": "V",
+    "QLD": "Q",
+    "SA": "S",
+    "WA": "W",
+    "TAS": "T",
+    "NT": "D",
+}
+
+# Town (précis) forecast product for each state.
+PRECIS_PRODUCTS: Final[dict[str, str]] = {
+    "NSW": "IDN11060",
+    "VIC": "IDV10753",
+    "QLD": "IDQ11295",
+    "SA": "IDS10044",
+    "WA": "IDW14199",
+    "TAS": "IDT16710",
+    "NT": "IDD10207",
+}
+
+# Official icon codes used by the BoM, mapped to the descriptor names used by
+# the BoM app API.
+ICON_DESCRIPTORS: Final[dict[int, str]] = {
+    1: "sunny",
+    2: "clear",
+    3: "mostly_sunny",
+    4: "cloudy",
+    6: "hazy",
+    8: "light_rain",
+    9: "windy",
+    10: "fog",
+    11: "shower",
+    12: "rain",
+    13: "dusty",
+    14: "frost",
+    15: "snow",
+    16: "storm",
+    17: "light_shower",
+    18: "heavy_shower",
+    19: "cyclone",
+}
+
+COMPASS_POINTS: Final[tuple[str, ...]] = (
+    "N",
+    "NNE",
+    "NE",
+    "ENE",
+    "E",
+    "ESE",
+    "SE",
+    "SSE",
+    "S",
+    "SSW",
+    "SW",
+    "WSW",
+    "W",
+    "WNW",
+    "NW",
+    "NNW",
+)

bom_weather_api/exceptions.py

@@ -0,0 +1,41 @@
+"""Exceptions raised by the Bureau of Meteorology API client."""
+
+from __future__ import annotations
+
+
+class BomError(Exception):
+    """Base exception for all client errors."""
+
+
+class BomConnectionError(BomError):
+    """The BoM API could not be reached."""
+
+
+class BomTimeoutError(BomConnectionError):
+    """A request to the BoM API timed out."""
+
+
+class BomResponseError(BomError):
+    """The BoM API returned an unexpected HTTP status."""
+
+    def __init__(self, message: str, *, status: int) -> None:
+        """Initialise the error with the HTTP status code."""
+        super().__init__(message)
+        self.status = status
+
+
+class BomNotFoundError(BomResponseError):
+    """The requested resource (place, station, warning) does not exist."""
+
+
+class BomRateLimitError(BomResponseError):
+    """The BoM API is rate limiting requests."""
+
+    def __init__(self, message: str, *, status: int, retry_after: int | None) -> None:
+        """Initialise the error with the server supplied retry delay."""
+        super().__init__(message, status=status)
+        self.retry_after = retry_after
+
+
+class BomParseError(BomError):
+    """The BoM API returned data that could not be parsed."""

bom_weather_api/ftp.py

@@ -0,0 +1,78 @@
+"""Transport for the BoM anonymous FTP server."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Protocol
+
+import aioftp
+
+from .const import DEFAULT_TIMEOUT, FTP_HOST
+from .exceptions import BomConnectionError, BomNotFoundError, BomTimeoutError
+
+# FTP reply code for "file unavailable".
+_FILE_UNAVAILABLE = "550"
+
+
+class FileTransport(Protocol):
+    """Something that can fetch a file from the BoM FTP server."""
+
+    async def fetch(self, path: str) -> bytes:
+        """Return the contents of the file at ``path``."""
+
+
+class FtpTransport:
+    """Download files from the BoM anonymous FTP server."""
+
+    def __init__(
+        self,
+        host: str = FTP_HOST,
+        *,
+        port: int = 21,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Initialise the transport."""
+        self._host = host
+        self._port = port
+        self._timeout = timeout
+
+    async def fetch(self, path: str) -> bytes:
+        """Download a file using an anonymous FTP session."""
+        try:
+            async with asyncio.timeout(self._timeout):
+                async with aioftp.Client.context(
+                    self._host,
+                    self._port,
+                    socket_timeout=self._timeout,
+                ) as client:
+                    await _ensure_exists(client, path)
+                    async with client.download_stream(path) as stream:
+                        chunks = [block async for block in stream.iter_by_block()]
+                    return b"".join(chunks)
+        except TimeoutError as err:
+            raise BomTimeoutError(f"Timeout downloading {path}") from err
+        except aioftp.StatusCodeError as err:
+            if _FILE_UNAVAILABLE in {str(code) for code in err.received_codes}:
+                raise BomNotFoundError(f"Not found: {path}", status=550) from err
+            raise BomConnectionError(f"FTP error downloading {path}: {err}") from err
+        except (OSError, aioftp.AIOFTPException) as err:
+            raise BomConnectionError(f"Error downloading {path}: {err}") from err
+
+
+async def _ensure_exists(client: aioftp.Client, path: str) -> None:
+    """Raise a 550 StatusCodeError if ``path`` does not exist.
+
+    The check runs on the control connection before RETR, because aioftp
+    leaks the data connection when RETR is refused.
+    """
+    await client.command("TYPE I", "200")
+    try:
+        await client.command(f"SIZE {path}", "213")
+    except aioftp.StatusCodeError as err:
+        if _FILE_UNAVAILABLE in {str(code) for code in err.received_codes}:
+            raise
+        # SIZE is not supported by every server; fall back to MLST.
+        if not await client.exists(path):
+            raise aioftp.StatusCodeError(
+                aioftp.Code("213"), aioftp.Code(_FILE_UNAVAILABLE), "not found"
+            ) from err

bom_weather_api/geohash.py

@@ -0,0 +1,29 @@
+"""Geohash encoding, used to address locations in the BoM app API."""
+
+from __future__ import annotations
+
+_BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz"
+
+
+def geohash_encode(latitude: float, longitude: float, precision: int = 6) -> str:
+    """Encode a coordinate as a geohash of the given precision."""
+    lat_range = [-90.0, 90.0]
+    lon_range = [-180.0, 180.0]
+    chars: list[str] = []
+    value = bits = 0
+    even = True
+    while len(chars) < precision:
+        bounds, coord = (lon_range, longitude) if even else (lat_range, latitude)
+        mid = (bounds[0] + bounds[1]) / 2
+        value <<= 1
+        if coord > mid:
+            value |= 1
+            bounds[0] = mid
+        else:
+            bounds[1] = mid
+        even = not even
+        bits += 1
+        if bits == 5:
+            chars.append(_BASE32[value])
+            value = bits = 0
+    return "".join(chars)