wevva 0.1.0__py3-none-any.whl

wevva/__init__.py

@@ -0,0 +1,50 @@
+"""Wevva package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from wevva.api import (
+    LocationNotFoundError,
+    WevvaAPIError,
+    forecast_by_coordinates,
+    forecast_by_coordinates_sync,
+    forecast_by_place,
+    forecast_by_place_sync,
+    geocode,
+    geocode_sync,
+)
+from wevva.location_metadata import LocationMetadata
+from wevva.models import ForecastBundle
+from wevva.openmeteo import (
+    CurrentOpenMeteoForecast,
+    DailyOpenMeteoForecast,
+    HourlyOpenMeteoForecast,
+)
+
+CurrentForecast = CurrentOpenMeteoForecast
+HourlyForecast = HourlyOpenMeteoForecast
+DailyForecast = DailyOpenMeteoForecast
+
+__all__ = [
+    "CurrentForecast",
+    "CurrentOpenMeteoForecast",
+    "DailyForecast",
+    "DailyOpenMeteoForecast",
+    "ForecastBundle",
+    "HourlyForecast",
+    "HourlyOpenMeteoForecast",
+    "LocationMetadata",
+    "LocationNotFoundError",
+    "WevvaAPIError",
+    "__version__",
+    "forecast_by_coordinates",
+    "forecast_by_coordinates_sync",
+    "forecast_by_place",
+    "forecast_by_place_sync",
+    "geocode",
+    "geocode_sync",
+]
+
+try:
+    __version__ = version("wevva")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

wevva/__main__.py

@@ -0,0 +1,11 @@
+"""Run Wevva via `python -m wevva`."""
+
+from wevva.cli import app
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

wevva/api.py

@@ -0,0 +1,281 @@
+"""Public library API for fetching weather without the TUI."""
+
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+from typing import Any, Awaitable, TypeVar
+
+from wevva.location_metadata import LocationMetadata
+from wevva.models import ForecastBundle
+from wevva.openmeteo import (
+    CurrentOpenMeteoForecast,
+    DailyOpenMeteoForecast,
+    HourlyOpenMeteoForecast,
+    OpenMeteoForecast,
+)
+from wevva.services.air_quality import fetch_air_quality
+from wevva.services.geocoding import search_places
+from wevva.services.weather import fetch_weather
+
+AIR_QUALITY_FIELDS: tuple[str, ...] = (
+    "us_aqi",
+    "european_aqi",
+    "pm2_5",
+    "pm10",
+    "ozone",
+    "grass_pollen",
+)
+T = TypeVar("T")
+
+
+class WevvaAPIError(RuntimeError):
+    """Base exception for public API helpers."""
+
+
+class LocationNotFoundError(WevvaAPIError):
+    """Raised when a place query returns no geocoding matches."""
+
+
+def _run_sync(coro: Awaitable[T]) -> T:
+    """Run an async coroutine from synchronous code."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    raise WevvaAPIError(
+        "Sync API cannot run inside an active event loop. Use async API functions instead."
+    )
+
+
+def _location_metadata_from_place(place: dict[str, Any]) -> LocationMetadata:
+    """Convert one geocoding result into ``LocationMetadata``."""
+    lat = place.get("latitude")
+    lon = place.get("longitude")
+    return LocationMetadata(
+        latitude=float(lat) if isinstance(lat, (int, float)) else None,
+        longitude=float(lon) if isinstance(lon, (int, float)) else None,
+        name=place.get("name") or "",
+        admin=place.get("admin") or "",
+        country=place.get("country") or "",
+        country_code=place.get("country_code") or "",
+        timezone=place.get("tz_identifier") or "",
+    )
+
+
+def _apply_place_metadata(
+    metadata: LocationMetadata, place: dict[str, Any] | None
+) -> None:
+    """Overlay geocoding place fields onto API metadata."""
+    if not place:
+        return
+    metadata.name = place.get("name") or metadata.name
+    metadata.admin = place.get("admin") or metadata.admin
+    metadata.country = place.get("country") or metadata.country
+    metadata.country_code = place.get("country_code") or metadata.country_code
+    if not metadata.timezone:
+        metadata.timezone = place.get("tz_identifier") or metadata.timezone
+
+
+def _merge_air_quality_fields(
+    hourly_data: dict[str, Any], air_quality: dict[str, Any] | None
+) -> dict[str, Any]:
+    """Attach air-quality lists to hourly weather data."""
+    merged = dict(hourly_data)
+    if not air_quality:
+        return merged
+    aq_hourly = air_quality.get("hourly")
+    if not isinstance(aq_hourly, dict):
+        return merged
+
+    weather_times = merged.get("time", [])
+    weather_count = len(weather_times) if isinstance(weather_times, list) else 0
+    for field in AIR_QUALITY_FIELDS:
+        values = aq_hourly.get(field)
+        if not isinstance(values, list):
+            continue
+        if len(values) < weather_count:
+            values = values + [None] * (weather_count - len(values))
+        elif len(values) > weather_count:
+            values = values[:weather_count]
+        merged[field] = values
+    return merged
+
+
+async def _build_forecast_bundle(
+    weather_data: dict[str, Any],
+    *,
+    country_code: str = "",
+    place: dict[str, Any] | None = None,
+) -> ForecastBundle:
+    """Build typed forecast models from raw API weather data."""
+    data = deepcopy(weather_data)
+    metadata = OpenMeteoForecast.extract_metadata(data)
+    _apply_place_metadata(metadata, place)
+
+    units_current = OpenMeteoForecast.extract_units(data, key="current")
+    units_hourly = OpenMeteoForecast.extract_units(data, key="hourly")
+    units_daily = OpenMeteoForecast.extract_units(data, key="daily")
+
+    hourly_data = data.get("hourly") if isinstance(data.get("hourly"), dict) else {}
+    times = hourly_data.get("time", []) if isinstance(hourly_data, dict) else []
+    start = times[0] if times else None
+    end = times[-1] if times else None
+
+    air_quality = None
+    if (
+        start
+        and end
+        and metadata.latitude is not None
+        and metadata.longitude is not None
+    ):
+        air_quality = await fetch_air_quality(
+            metadata.latitude,
+            metadata.longitude,
+            start,
+            end,
+            country_code or metadata.country_code,
+        )
+
+    merged_hourly = _merge_air_quality_fields(hourly_data, air_quality)
+    data["hourly"] = merged_hourly
+
+    current = CurrentOpenMeteoForecast(metadata, units_current, data.get("current", {}))
+    hourly = HourlyOpenMeteoForecast(metadata, units_hourly, merged_hourly)
+    daily = DailyOpenMeteoForecast(metadata, units_daily, data.get("daily", {}))
+
+    return ForecastBundle(
+        metadata=metadata,
+        current=current,
+        hourly=hourly,
+        daily=daily,
+        raw=data,
+    )
+
+
+async def geocode(
+    query: str,
+    *,
+    count: int = 5,
+    language: str = "en",
+) -> list[LocationMetadata]:
+    """Search for places and return normalized location metadata entries."""
+    places = await search_places(query, count=count, language=language)
+    return [_location_metadata_from_place(place) for place in places]
+
+
+def geocode_sync(
+    query: str,
+    *,
+    count: int = 5,
+    language: str = "en",
+) -> list[LocationMetadata]:
+    """Synchronous wrapper for :func:`geocode`."""
+    return _run_sync(geocode(query, count=count, language=language))
+
+
+async def forecast_by_coordinates(
+    *,
+    lat: float,
+    lon: float,
+    temperature_unit: str = "celsius",
+    wind_speed_unit: str = "kmh",
+    precipitation_unit: str = "mm",
+    country_code: str = "",
+) -> ForecastBundle:
+    """Fetch forecasts for explicit coordinates."""
+    weather_data = await fetch_weather(
+        lat=lat,
+        lon=lon,
+        temperature_unit=temperature_unit,
+        wind_speed_unit=wind_speed_unit,
+        precipitation_unit=precipitation_unit,
+    )
+    return await _build_forecast_bundle(weather_data, country_code=country_code)
+
+
+def forecast_by_coordinates_sync(
+    *,
+    lat: float,
+    lon: float,
+    temperature_unit: str = "celsius",
+    wind_speed_unit: str = "kmh",
+    precipitation_unit: str = "mm",
+    country_code: str = "",
+) -> ForecastBundle:
+    """Synchronous wrapper for :func:`forecast_by_coordinates`."""
+    return _run_sync(
+        forecast_by_coordinates(
+            lat=lat,
+            lon=lon,
+            temperature_unit=temperature_unit,
+            wind_speed_unit=wind_speed_unit,
+            precipitation_unit=precipitation_unit,
+            country_code=country_code,
+        )
+    )
+
+
+async def forecast_by_place(
+    query: str,
+    *,
+    language: str = "en",
+    temperature_unit: str = "celsius",
+    wind_speed_unit: str = "kmh",
+    precipitation_unit: str = "mm",
+) -> ForecastBundle:
+    """Geocode a place query and fetch forecasts for the best match."""
+    matches = await search_places(query, count=1, language=language)
+    if not matches:
+        raise LocationNotFoundError(f"No location found for query: {query!r}")
+
+    place = matches[0]
+    lat = place.get("latitude")
+    lon = place.get("longitude")
+    if not isinstance(lat, (int, float)) or not isinstance(lon, (int, float)):
+        raise WevvaAPIError(f"Geocoding result for {query!r} is missing coordinates.")
+
+    weather_data = await fetch_weather(
+        lat=float(lat),
+        lon=float(lon),
+        temperature_unit=temperature_unit,
+        wind_speed_unit=wind_speed_unit,
+        precipitation_unit=precipitation_unit,
+    )
+    return await _build_forecast_bundle(
+        weather_data,
+        country_code=place.get("country_code") or "",
+        place=place,
+    )
+
+
+def forecast_by_place_sync(
+    query: str,
+    *,
+    language: str = "en",
+    temperature_unit: str = "celsius",
+    wind_speed_unit: str = "kmh",
+    precipitation_unit: str = "mm",
+) -> ForecastBundle:
+    """Synchronous wrapper for :func:`forecast_by_place`."""
+    return _run_sync(
+        forecast_by_place(
+            query,
+            language=language,
+            temperature_unit=temperature_unit,
+            wind_speed_unit=wind_speed_unit,
+            precipitation_unit=precipitation_unit,
+        )
+    )
+
+
+__all__ = [
+    "LocationNotFoundError",
+    "WevvaAPIError",
+    "forecast_by_coordinates",
+    "forecast_by_coordinates_sync",
+    "forecast_by_place",
+    "forecast_by_place_sync",
+    "geocode",
+    "geocode_sync",
+]

wevva/app.py

@@ -0,0 +1,186 @@
+"""Textual TUI for displaying weather forecasts and warnings (mini version).
+
+Public-facing code should be easy to scan; this file adds concise
+comments to highlight major blocks, actions, and message handlers.
+Behavior remains unchanged.
+"""
+
+from typing import ClassVar
+
+from textual.app import App
+
+from wevva.controller import WeatherController  # central async orchestrator
+from wevva.location_metadata import LocationMetadata
+from wevva.messages import PlaceSelected, WeatherFetchFailed, WeatherUpdated
+from wevva.screens.help import HelpScreen
+from wevva.screens.search_screen import SearchScreen
+from wevva.screens.settings_screen import SettingsScreen
+from wevva.screens.weather_screen import WeatherScreen
+
+
+class Wevva(App, inherit_bindings=False):
+    """Minimal textual weather app showing current, next 24h, daily and warnings.
+
+    - Message-first architecture: widgets react to `WeatherUpdated`.
+    - Compose once, then update in place for new data.
+    - Keep IDs stable to maintain `wevva.tcss` compatibility.
+    """
+
+    CSS_PATH = "wevva.tcss"  # single theme stylesheet
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
+        ("q", "quit", "Quit"),  # exit the app
+        ("s", "search", "Search"),  # open place search screen
+        ("r", "refresh", "Refresh"),  # fetch latest forecast
+        ("h", "help", "Help"),  # show quick help
+        ("u", "settings", "Units"),  # open settings
+    ]
+
+    def __init__(
+        self,
+        initial_location: LocationMetadata | None = None,
+        emoji_enabled: bool = True,
+        theme_name: str | None = None,
+        temperature_unit: str = "celsius",
+        wind_speed_unit: str = "kmh",
+        precipitation_unit: str = "mm",
+        **kwargs,
+    ):
+        """Initialize application (no postcode required; starts with place search).
+
+        Sets up controller, location state, and a refresh guard.
+        """
+        super().__init__(**kwargs)
+        self.controller = WeatherController(
+            temperature_unit=temperature_unit,
+            wind_speed_unit=wind_speed_unit,
+            precipitation_unit=precipitation_unit,
+        )
+        self.sub_title = (
+            "Weather data from Open-Meteo"  # static subtitle for all screens
+        )
+        self.forecast_metadata = None  # LocationMetadata after first fetch
+        # unified location context (holds geocoded place + last forecast metadata)
+        self.location = initial_location or LocationMetadata()  # set from CLI or search
+        # Track whether the app started with a CLI-provided location and any successful fetch yet
+        self.started_with_cli_location = initial_location is not None
+        self._has_successful_fetch = False
+        # guard to prevent overlapping refreshes
+        self._refresh_in_flight = False  # debounce concurrent refreshes
+        # Emoji rendering toggle (widgets can read via self.app.emoji_enabled)
+        self.emoji_enabled = bool(emoji_enabled)
+        # Store unit preferences for widgets
+        self.temperature_unit = temperature_unit
+        self.wind_speed_unit = wind_speed_unit
+        self.precipitation_unit = precipitation_unit
+        # Initialize main weather screen once
+        self.weather_screen = WeatherScreen()
+        # Theme selection from CLI (validated by Textual during assignment)
+        if theme_name is not None:
+            self.theme = theme_name
+
+    async def on_mount(self):
+        """Start with search screen, or if location provided via CLI, fetch weather directly."""
+        if self.location.latitude is not None and self.location.longitude is not None:
+            self.push_screen(self.weather_screen)
+            await self.action_refresh()
+        else:
+            self.push_screen(SearchScreen())
+
+    # ------------------------------------------------------------
+    # Actions / key bindings
+    # ------------------------------------------------------------
+    async def action_refresh(self) -> None:
+        """Fetch via controller and broadcast `WeatherUpdated`.
+
+        Uses an in-flight guard to prevent overlapping requests.
+        """
+        if self._refresh_in_flight:
+            return
+        self._refresh_in_flight = True
+        try:
+            event = await self.controller.fetch(
+                lat=self.location.latitude,
+                lon=self.location.longitude,
+                country_code=self.location.country_code,
+            )
+            # Forward fresh data to the weather screen
+            self.weather_screen.post_message(event)
+        except Exception as e:
+            # Forward error to the weather screen to surface it
+            self.weather_screen.post_message(WeatherFetchFailed(e))
+        finally:
+            self._refresh_in_flight = False
+
+    def action_search(self):  # textual binding: 's'
+        """Open place search screen (fresh instance)."""
+        self.push_screen(SearchScreen())
+
+    def action_help(self):  # textual binding: 'h'
+        """Open help screen."""
+        self.push_screen(HelpScreen())
+
+    def action_settings(self) -> None:
+        """Open settings screen and handle result via callback."""
+        self.push_screen(
+            SettingsScreen(
+                temperature_unit=self.temperature_unit,
+                wind_speed_unit=self.wind_speed_unit,
+                precipitation_unit=self.precipitation_unit,
+            ),
+            callback=self._on_settings_result,
+        )
+
+    async def _on_settings_result(self, result: dict | None) -> None:
+        """Handle settings screen dismiss with optional result."""
+        # If user clicked Apply (result is dict), update units and refresh
+        if result:
+            self.temperature_unit = result["temperature_unit"]
+            self.wind_speed_unit = result["wind_speed_unit"]
+            self.precipitation_unit = result["precipitation_unit"]
+
+            # Update controller with new units
+            self.controller = WeatherController(
+                temperature_unit=self.temperature_unit,
+                wind_speed_unit=self.wind_speed_unit,
+                precipitation_unit=self.precipitation_unit,
+            )
+
+            # Refresh weather with new units
+            if (
+                self.location.latitude is not None
+                and self.location.longitude is not None
+            ):
+                await self.action_refresh()
+
+    # ---------------- Messages ----------------
+    async def on_place_selected(self, message: PlaceSelected) -> None:
+        """Handle place selection → fetch → show main content.
+
+        Adopts selected location first so widgets see correct context on WeatherUpdated.
+        """
+        self.location = message.location
+        self.push_screen(self.weather_screen)
+        await self.action_refresh()
+
+    async def on_weather_updated(self, event: WeatherUpdated) -> None:
+        """Cache forecast metadata and merge API data into location."""
+        self.forecast_metadata = event.metadata
+        # Merge API-provided fields into app location
+        if event.metadata.elevation is not None:
+            self.location.elevation = event.metadata.elevation
+        if event.metadata.timezone_abbreviation:
+            self.location.timezone_abbreviation = event.metadata.timezone_abbreviation
+        self._has_successful_fetch = True
+
+    async def on_weather_fetch_failed(self, event: WeatherFetchFailed) -> None:
+        """Show error notification; return to search if CLI location failed on first fetch."""
+        self.notify(
+            f"Refresh failed: {type(event.error).__name__}: {event.error}",
+            title="Weather Fetch Failed",
+            severity="error",
+            timeout=5.0,
+        )
+
+        # If CLI location failed on first fetch, return to search for recovery
+        if self.started_with_cli_location and not self._has_successful_fetch:
+            self.push_screen(SearchScreen())