python-meteolux 0.1.0__py3-none-any.whl

meteolux/__init__.py

@@ -0,0 +1,5 @@
+"""Module entry point."""
+
+from .async_api import AsyncMeteoLuxClient
+
+__all__ = ['AsyncMeteoLuxClient']

meteolux/async_api.py

@@ -0,0 +1,252 @@
+"""A Python client for the MeteoLux API."""
+import typing
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import NotFoundError
+from .models import (
+  ATCReport,
+  Bookmarks,
+  InObservation,
+  ObservationMetadataResponse,
+  ObservationResponse,
+  User,
+  WeatherResponse,
+)
+
+
+class AsyncMeteoLuxClient:
+  """A Python client for the MeteoLux API, built with httpx and Pydantic.
+
+  This client is generated from the OpenAPI specification and provides
+  methods for all available endpoints, returning structured Pydantic models.
+  """
+
+  def __init__(self, base_url: str = 'https://metapi.ana.lu/api/v1') -> None:
+    """Initializes the client with the base URL.
+
+    Args:
+        base_url (str): The base URL for the API.
+    """
+    self.base_url = base_url
+    self.client = httpx.AsyncClient(base_url=self.base_url, timeout=10.0)
+
+  async def _request(self, method: str, endpoint: str, response_model: Optional[Any] = None, **kwargs: Any) -> Any:
+    """Internal method to handle all API requests and common error handling.
+
+    Args:
+        method (str): The HTTP method (e.g., "GET", "POST").
+        endpoint (str): The API endpoint path.
+        response_model (Optional[Any]): The Pydantic model to use for response parsing.
+        **kwargs: Additional arguments for the httpx request (e.g., params, json).
+
+    Returns:
+        Any: The Pydantic model instance or raw JSON data.
+
+    Raises:
+        NotFoundError: If the API returns a 404 Not Found status code.
+        httpx.HTTPStatusError: If the response status code is another error.
+        httpx.RequestError: For network-related issues.
+    """
+    try:
+      response = await self.client.request(method, endpoint, **kwargs)
+      response.raise_for_status()
+
+      if response.status_code == 204:
+        return None
+
+      data = response.json()
+      if response_model:
+        return response_model.model_validate(data)
+      return data
+
+    except httpx.HTTPStatusError as exc:
+      if exc.response.status_code == 404:
+        raise NotFoundError(detail=exc.response.text) from exc
+
+      raise
+    except httpx.RequestError:
+      raise
+
+  # --- ATC Endpoints ---
+
+  async def get_atc_report(self) -> ATCReport:
+    """Get data for the ATC dashboard.
+
+    Corresponds to GET /atc/report.
+
+    Returns:
+        ATCReport: An ATCReport Pydantic model instance.
+    """
+    endpoint = '/atc/report'
+    return await self._request('GET', endpoint, response_model=ATCReport)
+
+  # --- HVD Endpoints ---
+
+  async def get_observations_hvd(self) -> ObservationResponse:
+    """Return last minute observation data.
+
+    Corresponds to GET /hvd/observations.
+
+    Returns:
+        ObservationResponse: An ObservationResponse Pydantic model instance.
+    """
+    endpoint = '/hvd/observations'
+    return await self._request('GET', endpoint, response_model=ObservationResponse)
+
+  async def get_observations_metadata_hvd(self) -> ObservationMetadataResponse:
+    """Return observations metadata.
+
+    Corresponds to GET /hvd/observations/metadata.
+
+    Returns:
+        ObservationMetadataResponse: An ObservationMetadataResponse Pydantic model instance.
+    """
+    endpoint = '/hvd/observations/metadata'
+    return await self._request('GET', endpoint, response_model=ObservationMetadataResponse)
+
+  async def get_station_information_hvd(self, station_id: str) -> list[Any]:
+    """Return station information, by ID.
+
+    Corresponds to GET /hvd/stations/{station_id}.
+
+    Args:
+        station_id (str): The ID of the station to retrieve.
+
+    Returns:
+        Any: Station data from the response. The OpenAPI spec indicates the return type is a list of Stations.
+    """
+    endpoint = f'/hvd/stations/{station_id}'
+    return await self._request('GET', endpoint)
+
+  async def get_all_station_information_hvd(self) -> list[Any]:
+    """Return all station information.
+
+    Corresponds to GET /hvd/stations.
+
+    Returns:
+        list[Any]: A list of station objects. The OpenAPI spec indicates the return type is a list of Stations.
+    """
+    endpoint = '/hvd/stations'
+    return await self._request('GET', endpoint)
+
+  # --- MetApp Endpoints ---
+
+  async def get_weather(self, langcode: str = 'fr', city: Optional[int] = None, lat: Optional[float] = None, long: Optional[float] = None) -> WeatherResponse:
+    """Get weather for a city/language or lat/long.
+
+    Corresponds to GET /metapp/weather.
+
+    Args:
+        langcode (str): The language code (fr, de, en, lb).
+        city (Optional[int]): The city ID.
+        lat (Optional[float]): Latitude.
+        long (Optional[float]): Longitude.
+
+    Returns:
+        WeatherResponse: A WeatherResponse Pydantic model instance.
+    """
+    endpoint = '/metapp/weather'
+    params: dict[str, str] = {'langcode': langcode}
+    if city is not None:
+      params['city'] = str(city)
+    if lat is not None:
+      params['lat'] = str(lat)
+    if long is not None:
+      params['long'] = str(long)
+    return await self._request('GET', endpoint, params=params, response_model=WeatherResponse)
+
+  async def update_user(self, user_data: User) -> None:
+    """Add or update a user's token and preferences.
+
+    Corresponds to POST /metapp/user.
+
+    Args:
+        user_data (User): A Pydantic User model instance.
+    """
+    endpoint = '/metapp/user'
+    await self._request('POST', endpoint, json=user_data.model_dump(by_alias=True))
+
+  async def get_bookmarks(self, langcode: str = 'fr', lat: Optional[float] = None, long: Optional[float] = None) -> Bookmarks:
+    """Return all cities and the closest one if lat/long are given.
+
+    Corresponds to GET /metapp/bookmarks.
+
+    Args:
+        langcode (str): The language code (fr, de, en, lb).
+        lat (Optional[float]): Latitude.
+        long (Optional[float]): Longitude.
+
+    Returns:
+        Bookmarks: A Bookmarks Pydantic model instance.
+    """
+    endpoint = '/metapp/bookmarks'
+    params: dict[str, str] = {'langcode': langcode}
+    if lat is not None:
+      params['lat'] = str(lat)
+    if long is not None:
+      params['long'] = str(long)
+    return await self._request('GET', endpoint, params=params, response_model=Bookmarks)
+
+  async def get_interface_texts(self, lang: typing.Literal['fr', 'de', 'en', 'lb'] = 'fr') -> dict[str, Any]:
+    """Return translated interface texts for the mobile app.
+
+    Note: The spec for this endpoint's response is an un-typed object.
+
+    Corresponds to GET /metapp/text.
+
+    Args:
+        lang (str): The language code (fr, de, en, lb).
+
+    Returns:
+        dict[str, Any]: A dictionary with translated strings.
+    """
+    endpoint = '/metapp/text'
+    params = {'lang': lang}
+    return await self._request('GET', endpoint, params=params)
+
+  async def stream_image(self, filename: str) -> httpx.Response:
+    """Stream an image from the cluster.
+
+    Corresponds to GET /metapp/image/{filename}.
+
+    Args:
+        filename (str): The name of the image file.
+
+    Returns:
+        httpx.Response: The raw httpx Response object to handle streaming.
+    """
+    endpoint = f'/metapp/image/{filename}'
+    return await self.client.get(endpoint, timeout=10.0)
+
+  async def get_observations_metapp(self) -> list[Any]:
+    """Return participative observations in the last 30 minutes.
+
+    Note: The spec for this endpoint's response is an array of untyped objects.
+
+    Corresponds to GET /metapp/observations.
+
+    Returns:
+        list[Any]: A list of objects.
+    """
+    endpoint = '/metapp/observations'
+    return await self._request('GET', endpoint)
+
+  async def add_observation(self, observation_data: InObservation) -> str:
+    """Add a new observation.
+
+    Corresponds to POST /metapp/observation.
+
+    Args:
+        observation_data (InObservation): An InObservation Pydantic model instance.
+
+    Returns:
+        str: The successful response message.
+    """
+    endpoint = '/metapp/observation'
+    return await self._request('POST', endpoint, json=observation_data.model_dump())
+
+  async def close(self) -> None:
+    """Closes the httpx client."""
+    await self.client.aclose()

meteolux/exceptions.py

@@ -0,0 +1,59 @@
+"""Custom exceptions for the MeteoLux API client."""
+
+
+class MeteoLuxError(Exception):
+  """Base exception for the MeteoLux API client."""
+
+
+class NotFoundError(MeteoLuxError):
+  """Raised when the API returns a 404 Not Found status."""
+
+  def __init__(self, detail: str) -> None:
+    """Initializes the NotFoundError with a detail message.
+
+    Args:
+        detail (str): The error message from the API.
+    """
+    self.detail = detail
+    super().__init__(self.detail)
+
+
+class ValidationError(MeteoLuxError):
+  """Raised when there is a validation error in the Pydantic models."""
+
+  def __init__(self, detail: str) -> None:
+    """Initializes the ValidationError with a detail message.
+
+    Args:
+        detail (str): The error message from the API.
+    """
+    self.detail = detail
+    super().__init__(self.detail)
+
+
+class HTTPValidationError(MeteoLuxError):
+  """Raised when the API returns a 422 Unprocessable Entity status."""
+
+  def __init__(self, detail: str) -> None:
+    """Initializes the HTTPValidationError with a detail message.
+
+    Args:
+        detail (str): The error message from the API.
+    """
+    self.detail = detail
+    super().__init__(self.detail)
+
+
+class HTTPError(MeteoLuxError):
+  """A generic HTTP error."""
+
+  def __init__(self, status_code: int, detail: str) -> None:
+    """Initializes the HTTPError with a status code and detail message.
+
+    Args:
+        status_code (int): The HTTP status code.
+        detail (str): The error message from the API.
+    """
+    self.status_code = status_code
+    self.detail = detail
+    super().__init__(f'HTTP Error {self.status_code}: {self.detail}')

meteolux/models.py

@@ -0,0 +1,331 @@
+"""API models."""
+
+from datetime import date, datetime
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class Icon(BaseModel):
+  """Base icon."""
+
+  id: int
+  name: str
+
+
+class Wind(BaseModel):
+  """Wind model."""
+
+  direction: str
+  speed: str
+  gusts: Optional[str] = None
+
+
+class Temperature(BaseModel):
+  """Temperature model."""
+
+  temperature: Union[int, list[int]]
+  humidex: Optional[str] = None
+  felt: Optional[int] = None
+
+
+class CurrentWeather(BaseModel):
+  """Part of the global weather model."""
+
+  date: datetime
+  icon: Icon
+  wind: Wind
+  rain: str
+  snow: str
+  type: Literal['current'] = 'current'
+  temperature: Temperature
+
+
+class DailyWeather(BaseModel):
+  """For the list of following days."""
+
+  date: datetime
+  icon: Icon
+  wind: Wind
+  rain: str
+  snow: str
+  type: Literal['daily'] = 'daily'
+  temperature_min: Temperature = Field(..., alias='temperatureMin')
+  temperature_max: Temperature = Field(..., alias='temperatureMax')
+  sunshine: int
+  uv_index: int = Field(..., alias='uvIndex')
+
+
+class HourlyWeather(BaseModel):
+  """For the list of following hours."""
+
+  date: datetime
+  icon: Icon
+  wind: Wind
+  rain: str
+  snow: str
+  type: Literal['hourly'] = 'hourly'
+  temperature: Temperature
+
+
+class Trend(BaseModel):
+  """Forecast part of data."""
+
+  date: date
+  min_temp: float = Field(..., alias='minTemp')
+  max_temp: float = Field(..., alias='maxTemp')
+  precipitation: float
+
+
+class Climatology(BaseModel):
+  """History part of data."""
+
+  date: datetime
+  min_temp: float = Field(..., alias='minTemp')
+  max_temp: float = Field(..., alias='maxTemp')
+  precipitation: float
+  mean_temp: float = Field(..., alias='meanTemp')
+  sunshine: Optional[float] = None
+
+
+class GraphicalData(BaseModel):
+  """Graphical group of data."""
+
+  history: list[Climatology]
+  forecast: list[Trend]
+
+
+class Vigilance(BaseModel):
+  """Vigilance model."""
+
+  datetime_start: datetime = Field(..., alias='datetimeStart')
+  datetime_end: datetime = Field(..., alias='datetimeEnd')
+  level: Literal[2, 3, 4]
+  type: int
+  group: int
+  region: Literal['north', 'south', 'all']
+  description: str
+
+
+class RoadStatusItem(BaseModel):
+  """Road status item model as per the spec."""
+
+  date: Union[date, list[str]]
+  description: str
+
+
+class ImageOut(BaseModel):
+  """Image with url."""
+
+  date: datetime
+  provider: str
+  url: str = Field(..., max_length=2083, min_length=1)
+
+
+class Radar(BaseModel):
+  """Radar image model."""
+
+  real_time: list[ImageOut] = Field(..., alias='realTime')
+  forecast: list[ImageOut]
+
+
+class Satellite(BaseModel):
+  """Satellite image model."""
+
+  infrared: list[ImageOut]
+  visual: list[ImageOut]
+
+
+class MoonIcon(BaseModel):
+  """As different id are used."""
+
+  id: str
+  name: str
+
+
+class Ephemeris(BaseModel):
+  """Ephemeris model."""
+
+  date: date
+  sunrise: str
+  sunset: str
+  moonrise: str
+  moonset: str
+  sunshine: str
+  moon_icon: MoonIcon = Field(..., alias='moonIcon')
+  uv_index: int = Field(..., alias='uvIndex', ge=0.0, le=12.0)
+
+
+class ATCReportForecast(BaseModel):
+  """Forecast for ATC dashboard."""
+
+  hourly: list['HourlyWindForecast']
+
+
+class ATCReport(BaseModel):
+  """Data for ATC dashboard."""
+
+  forecast: ATCReportForecast
+
+
+class HourlyWindForecast(BaseModel):
+  """Hourly wind report, at different altitude (feet)."""
+
+  date: datetime
+  qnh: int
+  wind: Wind
+  wind1500: Wind
+  wind2500: Wind
+  wind5000: Wind
+  wind10000: Wind
+
+
+class BookmarkCity(BaseModel):
+  """With additional info for mobile app ep."""
+
+  id: int
+  name: str
+  region: Literal['N', 'S'] = 'S'
+  canton: Literal[
+    'Capellen', 'Clervaux', 'Diekirch', 'Echternach', 'Esch-sur-Alzette', 'Grevenmacher', 'Luxembourg', 'Mersch', 'Redange', 'Remich', 'Vianden', 'Wiltz'
+  ]
+  domain: Literal['villes', 'lieu', 'fluvial']
+  lat: float
+  long: float
+  temperature: float
+  icon: Icon
+
+
+class Bookmarks(BaseModel):
+  """Bookmarks model."""
+
+  cities: list[BookmarkCity]
+  nearest_city: Optional[BookmarkCity] = Field(None, alias='nearestCity')
+
+
+class InObservation(BaseModel):
+  """Observation from public users."""
+
+  lat: float = Field(..., ge=-90.0, le=90.0)
+  long: float = Field(..., ge=-180.0, le=180.0)
+  description: str = Field(..., max_length=1024)
+  weather: int
+
+
+class SensorLevel(BaseModel):
+  """Sensor level definition."""
+
+  level_type: Literal['height_above_ground'] = Field(..., alias='levelType')
+  unit: Literal['m']
+  value: float = Field(..., ge=0.0)
+
+
+class ObservationMetadata(BaseModel):
+  """Sensor definition."""
+
+  id: str
+  name: str
+  description: str
+  data_type: Literal['realtime', 'climate'] = Field(..., alias='dataType')
+  unit: Literal['m', 'm/s', '%', '1/10 kt', 'degC', 'degrees', 'ft', 'hPa', 'mm']
+  category: Literal['Wind', 'Cloud Cover', 'Atmospheric pressure', 'Precipitation', 'Temperature', 'Humidity', 'Visibility']
+  performance_category: Literal['A', 'B', 'C', 'D', 'E'] = Field(..., alias='performanceCategory')
+  qualitycode: Literal[0, 1, 2, 3, 4, 5, 6, 7]
+  timeoffsets: Literal['PT0H']
+  timeresolution: Literal['PT1M', 'PT1H']
+  sensorlevels: Optional[SensorLevel] = None
+
+
+class ObservationMetadataResponse(BaseModel):
+  """Elements metadata."""
+
+  licence: list[str] = ['Creative Commons', 'https://creativecommons.org/public-domain/cc0/']
+  doc_url: str = Field('/docs', alias='docUrl')
+  data: list[ObservationMetadata]
+  total_item_count: int = Field(1, alias='totalItemCount')
+  quality_codes: dict[str, str] = Field({'0': 'Value is controlled and found O.K.'}, alias='qualityCodes')
+  performance_category: dict[str, str] = Field(
+    {'A': 'The sensor type fulfills the requirements from WMO/CIMOs on measurement accuracy, calibration and maintenance.'}, alias='performanceCategory'
+  )
+
+
+class ObservationResponseData(BaseModel):
+  """Model to link gendata id to their values."""
+
+  id: str
+  value: Union[int, float]
+
+
+class ObservationResponse(BaseModel):
+  """Last Observations."""
+
+  licence: list[str] = ['Creative Commons', 'https://creativecommons.org/public-domain/cc0/']
+  doc_url: str = Field('/docs', alias='docUrl')
+  data: list[ObservationResponseData]
+  total_item_count: int = Field(1, alias='totalItemCount')
+  timestamp: datetime
+
+
+class OutCity(BaseModel):
+  """City with translated name."""
+
+  id: int
+  name: str
+  region: Literal['N', 'S'] = 'S'
+  canton: Literal[
+    'Capellen', 'Clervaux', 'Diekirch', 'Echternach', 'Esch-sur-Alzette', 'Grevenmacher', 'Luxembourg', 'Mersch', 'Redange', 'Remich', 'Vianden', 'Wiltz'
+  ]
+  domain: Literal['villes', 'lieu', 'fluvial']
+  lat: float
+  long: float
+
+
+class VigilanceSettings(BaseModel):
+  """User settings for notifications."""
+
+  level: Literal[2, 3, 4]
+  type_air: bool = Field(False, alias='typeAir')
+  type_cold: bool = Field(False, alias='typeCold')
+  type_flooding: bool = Field(False, alias='typeFlooding')
+  type_heat: bool = Field(False, alias='typeHeat')
+  type_ice: bool = Field(False, alias='typeIce')
+  type_rain: bool = Field(False, alias='typeRain')
+  type_snow: bool = Field(False, alias='typeSnow')
+  type_storm: bool = Field(False, alias='typeStorm')
+  type_wind: Optional[bool] = Field(None, alias='typeWind')
+  zone_north: bool = Field(..., alias='zoneNorth')
+  zone_south: bool = Field(..., alias='zoneSouth')
+
+
+class User(BaseModel):
+  """User model."""
+
+  language: Literal['fr', 'de', 'en', 'lb']
+  push_token: str = Field(..., alias='pushToken', max_length=50)
+  push_morning: bool = Field(False, alias='pushMorning')
+  push_evening: bool = Field(False, alias='pushEvening')
+  device: str
+  version: str
+  buildversion: str
+  vigilance: VigilanceSettings
+
+
+class WeatherResponseForecast(BaseModel):
+  """Forecast model."""
+
+  current: CurrentWeather
+  hourly: list[HourlyWeather]
+  daily: list[DailyWeather]
+
+
+class WeatherResponse(BaseModel):
+  """Final weather output from the backend."""
+
+  city: OutCity
+  forecast: WeatherResponseForecast
+  vigilances: list[Vigilance]
+  road_status: list[RoadStatusItem] = Field(..., alias='roadStatus')
+  ephemeris: Ephemeris
+  radar: Radar
+  satellite: Satellite
+  data: GraphicalData

python_meteolux-0.1.0.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: python-meteolux
+Version: 0.1.0
+Summary: python library for accessing the MeteoLux REST API
+Project-URL: Homepage, https://github.com/sim0nx/python-meteolux
+Project-URL: Download, https://github.com/sim0nx/python-meteolux
+Project-URL: Tracker, https://github.com/sim0nx/python-meteolux/issues
+Project-URL: Documentation, http://python-meteolux.readthedocs.io/en/latest/?badge=latest
+Project-URL: Source, https://github.com/sim0nx/python-meteolux
+Author-email: Georges Toth <georges@trypill.org>
+License: AGPLv3+
+Keywords: MeteoLux
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: httpx
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+An early implementation of the MeteoLux REST API.
+
+https://metapi.ana.lu/api/v1/docs

python_meteolux-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+meteolux/__init__.py,sha256=SOvcvxmHp7DoSe68cohBEmGHrh7FyYLJ8or4HlCL03k,105
+meteolux/async_api.py,sha256=0qs9bWBFOKbTSw2FAPiclWtEIKc7CPXV1QV1WTzJh40,8034
+meteolux/exceptions.py,sha256=eGiv_oDBHfEDQ0vHNGnekELt43seRusYMk3vBqfSBgg,1630
+meteolux/models.py,sha256=-J7mirv69yTm2RMl7tlH0qnLXs3qWTaTCKE1-kE893Q,8062
+python_meteolux-0.1.0.dist-info/METADATA,sha256=alcXHlWcjNsL07sPX3v4xBlVaucVUqmeorw7VWOKdj0,1291
+python_meteolux-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+python_meteolux-0.1.0.dist-info/RECORD,,

python_meteolux-0.1.0.dist-info/WHEEL

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