WeatherClient

This class provides a simple wrapper for the OpenWeathermap (OWM) and Open Meteo weather providers. It returns the current and forecast weather for the designated location.

The class will attempt to retrieve the weather data from the providers in this order:

1. OWM paid subscription (valid OWM "One Call" API Key required).
2. OWM free tier (valid OWM free server API Key required).
3. Open Meteo weather (no API key needed)

For the first two options, an OWM API key is required. You can obtain one at https://openweathermap.org.

Weather conditions are normalized to WMO weather codes internally so both providers return the same sky-condition model. Each reading includes:

1. A normalized WeatherDisplayInfo payload with the WMO code, canonical condition enum, day/night variant, icon name, and unicode character.
2. Required AstralInfo metadata with sunrise/sunset times plus sunrise/sunset icon names and emoji.
3. Reading-level precipitation and wind icon metadata.

SVG assets for the supported icon libraries are bundled with the package. WeatherClient can be configured with:

1. icon_library="meteocons" with themes fill-static, fill-animated, line-static, line-animated, or monochrome-static.
2. icon_library="weather-icons" with theme default.

The client returns icon names and packaged SVG assets; it does not generate hosted icon URLs. Applications that render icons should serve the bundled SVGs themselves or export them via the icon provider helper.

In all instances the WeatherClient weather look methods (e.g. get_weather()) return a WeatherData dataclass:

  """Data models for WeatherClient."""
  from __future__ import annotations

  from dataclasses import dataclass
  from datetime import datetime
  from enum import Enum


  class WeatherCondition(Enum):
      """Normalized weather conditions used across providers and icon libraries."""

      UNKNOWN = "unknown"
      CLEAR = "clear"
      PARTLY_CLOUDY = "partly_cloudy"
      CLOUDY = "cloudy"
      OVERCAST = "overcast"
      FOG = "fog"
      DRIZZLE = "drizzle"
      RAIN = "rain"
      SLEET = "sleet"
      SNOW = "snow"
      HAIL = "hail"
      THUNDERSTORM = "thunderstorm"
      HAZE = "haze"
      SMOKE = "smoke"
      DUST = "dust"
      WIND = "wind"


  @dataclass
  class Temperature:
      reading: float
      high: float | None = None
      low: float | None = None
      feels_like: float | None = None
      units: str = "C"


  @dataclass
  class WeatherDisplayInfo:
      wmo_code: int
      condition_key: WeatherCondition
      day_night_variant: str | None
      icon_name: str
      unicode_char: str | None = None


  @dataclass
  class SkyCondition:
      title: str
      description: str
      icon_info: WeatherDisplayInfo
      cloud_cover: float | None = None
      visibility: int | None = None
      uv_index: float | None = None


  @dataclass
  class Wind:
      speed: float
      deg: float | None
      direction: str | None = None
      gust: float | None = None
      units: str = "km/h"


  @dataclass
  class AstralInfo:
      sunrise: datetime
      sunset: datetime
      sunrise_icon_name: str
      sunrise_unicode_char: str
      sunset_icon_name: str
      sunset_unicode_char: str


  @dataclass
  class WeatherReading:
      utc_time: datetime
      local_time: datetime
      temperature: Temperature
      sky: SkyCondition
      wind: Wind
      astral_info: AstralInfo
      precipitation_icon_name: str
      precipitation_unicode_char: str
      wind_icon_name: str
      wind_unicode_char: str
      summary: str | None = None
      precip_probability: float | None = None
      rain: float | None = None
      pressure: float | None = None
      humidity: float | None = None
      dew_point: float | None = None


  @dataclass
  class WeatherStation:
      source: str
      latitude: float
      longitude: float
      timezone_name: str | None = None
      timezone_offset: int | None = None


  @dataclass
  class WeatherData:
      current: WeatherReading
      hourly: list[WeatherReading]
      daily: list[WeatherReading]
      station: WeatherStation
      as_at: datetime

__init__(latitude, longitude, owm_api_key=None, icon_library='meteocons', icon_theme=None)

Initialize the WeatherClient.

Parameters:

Name	Type	Description	Default
latitude	float	Latitude of the location to fetch weather for.	required
longitude	float	Longitude of the location to fetch weather for.	required
owm_api_key	str | None	Optional OpenWeatherMap API key for enhanced data.	None
icon_library	str	Icon library to use for display metadata.	'meteocons'
icon_theme	str | None	Optional icon theme/style for the selected library.	None

get_open_meteo_weather()

Fetch weather data from Open Meteo.

Returns:

Type	Description
WeatherData	A WeatherData object containing the current reading, list of hourly readings, and weather station info.

get_open_weather_map_weather(owm_api_key=None)

Fetch weather data from OpenWeatherMap.

Parameters:

Name	Type	Description	Default
owm_api_key	str | None	Optional OpenWeatherMap API key to use for this fetch. If provided, it will override the client's default key for this call.	None

Raises:

Type	Description
RuntimeError	If the OWM API key is not set or if the request fails.

Returns:

Type	Description
WeatherData	A WeatherData object containing the current reading, list of hourly readings, and weather station info.

get_weather(first_choice=None, owm_api_key=None)

Fetch weather data from providers, falling back as needed.

This method will try to get the current and forecast weather data from the following providers in order: 1. OpenWeatherMap v3 "One Call" service (if a valid API key is available that has a one-call subscription) 2. OpenWeatherMap v2.5 free service (if a valid OWM free API key is available) 3. Open-Meteo (as a fallback if OWM fails or is unavailable)

The preferred provider order can be influenced by the first_choice argument, but the method will automatically fall back to the next provider if the first choice fails for any reason (e.g., network error, API error, invalid API key).

Parameters:

Name	Type	Description	Default
first_choice	str | None	Optional string indicating the preferred weather provider ("owm" or "open_meteo").	None
owm_api_key	str | None	Optional OpenWeatherMap API key to use for this fetch. If provided, it will override the client's default key for this call.	None

Raises:

Type	Description
RuntimeError	If all providers fail to fetch weather data.

Returns:

Type	Description
WeatherData	A WeatherData object containing the current reading, list of hourly readings, and weather station info.