meteocatpy 0.0.7

package/meteocatpy/README.md

@@ -0,0 +1,62 @@
+# Meteocat Python Package for Meteocat Home Assistant Integration
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python version compatibility](https://img.shields.io/pypi/pyversions/meteocatpy)](https://pypi.org/project/meteocatpy)
+[![pipeline status](https://gitlab.com/figorr/meteocatpy/badges/master/pipeline.svg)](https://gitlab.com/figorr/meteocatpy/commits/master)
+
+
+`meteocatpy` is a Python package to interact with the Meteocat API. Allows you to obtain meteorological data and lists of municipalities from the Meteocat API.
+
+**NOTE:** Meteocat API requires to use an API_KEY, you should ask to (https://apidocs.meteocat.gencat.cat/documentacio/acces-ciutada-i-administracio/)
+
+# Installation
+
+You can install the package from PyPI using `pip`:
+```bash
+pip install meteocatpy
+```
+
+```bash
+from meteocatpy.town import MeteocatTown
+
+# Replace 'tu_api_key' with your actual API key
+API_KEY = "tu_api_key"
+town_client = MeteocatTown(API_KEY)
+
+# Get a list of municipalities (asynchronous call)
+municipios_data = await town_client.get_municipis()
+print(municipis)
+```
+
+# Credits
+
+This is a personal project.
+
+Authors:
+- Figorr
+
+# Contributing
+
+If you would like to contribute to this project, please open an issue or create a pull request. I'd be happy to review your contributions!
+
+1.  [Check for open features/bugs](https://gitlab.com/figorr/meteocatpy/issues)
+    or [initiate a discussion on one](https://gitlab.com/figorr/meteocatpy/issues/new).
+2.  [Fork the repository](https://gitlab.com/figorr/meteocatpy/forks/new).
+3.  Install the dev environment: `make init`.
+4.  Enter the virtual environment: `pipenv shell`
+5.  Code your new feature or bug fix.
+6.  Write a test that covers your new functionality.
+7.  Update `README.md` with any new documentation.
+8.  Run tests and ensure 100% code coverage for your contribution: `make coverage`
+9.  Ensure you have no linting errors: `make lint`
+10. Ensure you have typed your code correctly: `make typing`
+11. Add yourself to `AUTHORS.md`.
+12. Submit a pull request!
+
+# License
+
+[Apache-2.0](LICENSE). By providing a contribution, you agree the contribution is licensed under Apache-2.0.
+
+# API Reference
+
+[See the docs 📚](https://apidocs.meteocat.gencat.cat/section/informacio-general/).

package/meteocatpy/__init__.py

@@ -0,0 +1,27 @@
+"""METEOCAT API.
+
+Python Package to collect data from Meteocat API and interact with Meteocat Home Assistant Integration
+SPDX-License-Identifier: Apache-2.0
+
+For more details about this API, please refer to the documentation at
+https://gitlab.com/figorr/meteocatpy
+"""
+
+# meteocatpy/__init__.py
+from .town import MeteocatTown
+from .forecast import MeteocatForecast
+from .symbols import MeteocatSymbols
+from .stations import MeteocatStations
+from .townstations import MeteocatTownStations
+from .data import MeteocatStationData
+from .variables import MeteocatVariables
+
+__all__ = [
+    "MeteocatTown", 
+    "MeteocatForecast", 
+    "MeteocatSymbols", 
+    "MeteocatStations", 
+    "MeteocatTownStations", 
+    "MeteocatStationData", 
+    "MeteocatVariables"
+]

package/meteocatpy/const.py

@@ -0,0 +1,10 @@
+"""meteocatpy constants."""
+BASE_URL = "https://api.meteo.cat"
+MUNICIPIS_LIST_URL = "/referencia/v1/municipis"
+MUNICIPIS_HORA_URL = "/pronostic/v1/municipalHoraria/{codi}"
+MUNICIPIS_DIA_URL = "/pronostic/v1/municipal/{codi}"
+SYMBOLS_URL = "/referencia/v1/simbols"
+STATIONS_LIST_URL = "/xema/v1/estacions/metadades"
+STATIONS_MUNICIPI_URL = "/xema/v1/representatives/metadades/municipis/{codi_municipi}/variables/{codi_variable}"
+VARIABLES_URL = "/xema/v1/variables/mesurades/metadades"
+STATION_DATA_URL = "/xema/v1/estacions/mesurades/{codiEstacio}/{any}/{mes}/{dia}"

package/meteocatpy/data.py

@@ -0,0 +1,140 @@
+import aiohttp
+import logging
+from datetime import datetime
+from .variables import MeteocatVariables
+from .const import BASE_URL, STATION_DATA_URL
+from .exceptions import (
+    BadRequestError,
+    ForbiddenError,
+    TooManyRequestsError,
+    InternalServerError,
+    UnknownAPIError,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+class MeteocatStationData:
+    """Clase para interactuar con los datos de estaciones de la API de Meteocat."""
+
+    def __init__(self, api_key: str):
+        """
+        Inicializa la clase MeteocatStationData.
+
+        Args:
+            api_key (str): Clave de API para autenticar las solicitudes.
+        """
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key": self.api_key,
+        }
+        self.variables = MeteocatVariables(api_key)
+    
+    @staticmethod
+    def get_current_date():
+        """
+        Obtiene la fecha actual en formato numérico.
+
+        Returns:
+            tuple: Año (YYYY), mes (MM), día (DD) como enteros.
+        """
+        now = datetime.now()
+        return now.year, now.month, now.day
+
+    async def get_station_data(self, station_id: str):
+        """
+        Obtiene los datos meteorológicos de una estación desde la API de Meteocat.
+
+        Args:
+            station_id (str): Código de la estación.
+
+        Returns:
+            dict: Datos meteorológicos de la estación.
+        """
+        any, mes, dia = self.get_current_date()  # Calcula la fecha actual
+        url = f"{BASE_URL}{STATION_DATA_URL}".format(
+            codiEstacio=station_id, any=any, mes=f"{mes:02d}", dia=f"{dia:02d}"
+        )
+    
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(url, headers=self.headers) as response:
+                    if response.status == 200:
+                        return await response.json()
+
+                    # Gestionar errores según el código de estado
+                    if response.status == 400:
+                        raise BadRequestError(await response.json())
+                    elif response.status == 403:
+                        error_data = await response.json()
+                        if error_data.get("message") == "Forbidden":
+                            raise ForbiddenError(error_data)
+                        elif error_data.get("message") == "Missing Authentication Token":
+                            raise ForbiddenError(error_data)
+                    elif response.status == 429:
+                        raise TooManyRequestsError(await response.json())
+                    elif response.status == 500:
+                        raise InternalServerError(await response.json())
+                    else:
+                        raise UnknownAPIError(
+                            f"Unexpected error {response.status}: {await response.text()}"
+                        )
+
+            except aiohttp.ClientError as e:
+                raise UnknownAPIError(
+                    message=f"Error al conectar con la API de Meteocat: {str(e)}",
+                    status_code=0,
+                )
+
+            except Exception as ex:
+                raise UnknownAPIError(
+                    message=f"Error inesperado: {str(ex)}",
+                    status_code=0,
+                )
+
+    async def get_station_data_with_variables(self, station_id: str, force_update=False):
+        """
+        Obtiene los datos meteorológicos de una estación, organizados por variables.
+
+        Args:
+            station_id (str): Código de la estación.
+            force_update (bool): Si True, fuerza la actualización de las variables desde la API.
+
+        Returns:
+            dict: Datos organizados por variables.
+        """
+        # Obtener datos de la estación
+        station_data = await self.get_station_data(station_id)
+
+        # Registrar la respuesta para depuración
+        _LOGGER.debug("Datos de la estación (crudos): %s", station_data)
+
+        # Obtener las variables desde el caché o API
+        variables = await self.variables.get_variables(force_update=force_update)
+
+        # Crear una estructura para organizar los datos por variables
+        datos_por_variable = {}
+
+        # Recorrer cada estación en los datos devueltos
+        for estacion in station_data:
+            # Recorrer cada variable dentro de la estación
+            for variable in estacion.get("variables", []):
+                codi_variable = variable.get("codi")
+                variable_info = next((v for v in variables if v["codi"] == codi_variable), None)
+                if variable_info:
+                    nombre_variable = variable_info["nom"]
+                    if nombre_variable not in datos_por_variable:
+                        datos_por_variable[nombre_variable] = []
+
+                    # Agregar las lecturas de la variable
+                    for lectura in variable.get("lectures", []):
+                        datos_por_variable[nombre_variable].append(
+                            {
+                                "data": lectura["data"],
+                                "valor": lectura["valor"],
+                                "estat": lectura.get("estat", ""),
+                                "base_horaria": lectura.get("baseHoraria", ""),
+                            }
+                        )
+
+        return datos_por_variable

package/meteocatpy/exceptions.py

@@ -0,0 +1,35 @@
+"""METEOCAT API exceptions."""
+
+from __future__ import annotations
+
+class MeteocatAPIError(Exception):
+    """Clase base para todos los errores de la API de Meteocat."""
+    def __init__(self, message: str, status_code: int, aws_info: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.aws_info = aws_info
+
+class BadRequestError(MeteocatAPIError):
+    """Error 400: Bad request."""
+    def __init__(self, message: str, aws_info: dict = None):
+        super().__init__(message, 400, aws_info)
+
+class ForbiddenError(MeteocatAPIError):
+    """Error 403: Forbidden."""
+    def __init__(self, message: str, aws_info: dict = None):
+        super().__init__(message, 403, aws_info)
+
+class TooManyRequestsError(MeteocatAPIError):
+    """Error 429: Too many requests."""
+    def __init__(self, message: str, aws_info: dict = None):
+        super().__init__(message, 429, aws_info)
+
+class InternalServerError(MeteocatAPIError):
+    """Error 500: Internal server error."""
+    def __init__(self, message: str, aws_info: dict = None):
+        super().__init__(message, 500, aws_info)
+
+class UnknownAPIError(MeteocatAPIError):
+    """Error desconocido de la API."""
+    def __init__(self, message: str, status_code: int, aws_info: dict = None):
+        super().__init__(message, status_code, aws_info)

package/meteocatpy/forecast.py

@@ -0,0 +1,137 @@
+import aiohttp
+from .const import (
+    BASE_URL,
+    MUNICIPIS_HORA_URL,
+    MUNICIPIS_DIA_URL
+)
+from .exceptions import (
+    BadRequestError,
+    ForbiddenError,
+    TooManyRequestsError,
+    InternalServerError,
+    UnknownAPIError
+)
+
+class MeteocatForecast:
+    """Clase para interactuar con las predicciones de la API de Meteocat."""
+
+    def __init__(self, api_key: str):
+        """
+        Inicializa la clase MeteocatForecast.
+
+        Args:
+            api_key (str): Clave de API para autenticar las solicitudes.
+        """
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key": self.api_key,
+        }
+
+    async def _fetch_data(self, url: str):
+        """
+        Método genérico para realizar solicitudes a la API.
+
+        Args:
+            url (str): URL de la API a consultar.
+
+        Returns:
+            dict: Respuesta JSON de la API.
+        """
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(url, headers=self.headers) as response:
+                    if response.status == 200:
+                        return await response.json()
+
+                    # Gestionar errores según el código de estado
+                    if response.status == 400:
+                        raise BadRequestError(await response.json())
+                    elif response.status == 403:
+                        error_data = await response.json()
+                        if error_data.get("message") == "Forbidden":
+                            raise ForbiddenError(error_data)
+                        elif error_data.get("message") == "Missing Authentication Token":
+                            raise ForbiddenError(error_data)
+                    elif response.status == 429:
+                        raise TooManyRequestsError(await response.json())
+                    elif response.status == 500:
+                        raise InternalServerError(await response.json())
+                    else:
+                        raise UnknownAPIError(f"Unexpected error {response.status}: {await response.text()}")
+            except aiohttp.ClientError as e:
+                raise UnknownAPIError(
+                    message=f"Error al conectar con la API de Meteocat: {str(e)}",
+                    status_code=0,
+                )
+            except Exception as ex:
+                raise UnknownAPIError(
+                    message=f"Error inesperado: {str(ex)}",
+                    status_code=0,
+                )
+
+    async def get_prediccion_horaria(self, town_id: str):
+        """
+        Obtiene la predicción horaria a 72 horas para un municipio.
+
+        Args:
+            town_id (str): Código del municipio.
+
+        Returns:
+            dict: Predicción horaria para el municipio.
+        """
+        url = f"{BASE_URL}{MUNICIPIS_HORA_URL.format(codi=town_id)}"
+        return await self._fetch_data(url)
+
+    async def get_prediccion_diaria(self, town_id: str):
+        """
+        Obtiene la predicción diaria a 8 días para un municipio.
+
+        Args:
+            town_id (str): Código del municipio.
+
+        Returns:
+            dict: Predicción diaria para el municipio.
+        """
+        url = f"{BASE_URL}{MUNICIPIS_DIA_URL.format(codi=town_id)}"
+        return await self._fetch_data(url)
+
+    @staticmethod
+    def procesar_prediccion(prediccion_json):
+        """
+        Procesa el JSON de predicción y organiza los datos por variables.
+
+        Args:
+            prediccion_json (dict): JSON devuelto por la API de predicción.
+
+        Returns:
+            dict: Datos organizados por variables.
+        """
+        datos_por_variable = {}
+
+        # Iterar sobre los días en el JSON
+        for dia in prediccion_json.get("dies", []):
+            fecha = dia.get("data")
+
+            for variable, valores in dia.get("variables", {}).items():
+                if "valors" in valores:  # Predicción horaria
+                    for valor in valores["valors"]:
+                        nombre_variable = variable
+                        if nombre_variable not in datos_por_variable:
+                            datos_por_variable[nombre_variable] = []
+                        datos_por_variable[nombre_variable].append({
+                            "fecha": valor["data"],
+                            "valor": valor["valor"],
+                            "unidad": valores.get("unitat", ""),
+                        })
+                else:  # Predicción diaria
+                    nombre_variable = variable
+                    if nombre_variable not in datos_por_variable:
+                        datos_por_variable[nombre_variable] = []
+                    datos_por_variable[nombre_variable].append({
+                        "fecha": fecha,
+                        "valor": valores["valor"],
+                        "unidad": valores.get("unitat", ""),
+                    })
+
+        return datos_por_variable

package/meteocatpy/helpers.py

@@ -0,0 +1,46 @@
+"""Meteocat Helpers."""
+
+from datetime import datetime
+from typing import Any
+import re
+import unicodedata
+from zoneinfo import ZoneInfo
+
+TZ_UTC = ZoneInfo("UTC")
+
+
+def dict_nested_value(data: dict[str, Any] | None, keys: list[str] | None) -> Any:
+    """Get value from dict with nested keys."""
+    if keys is None or len(keys) == 0:
+        return None
+    for key in keys or {}:
+        if data is not None:
+            data = data.get(key)
+    return data
+
+
+def get_current_datetime(tz: ZoneInfo = TZ_UTC, replace: bool = True) -> datetime:
+    """Return current datetime in UTC."""
+    cur_dt = datetime.now(tz=tz)
+    if replace:
+        cur_dt = cur_dt.replace(minute=0, second=0, microsecond=0)
+    return cur_dt
+
+
+def parse_api_timestamp(timestamp: str, tz: ZoneInfo = TZ_UTC) -> datetime:
+    """Parse API timestamp into datetime."""
+    return datetime.fromisoformat(timestamp).replace(tzinfo=tz)
+
+
+def slugify(value: str, allow_unicode: bool = False) -> str:
+    """Convert string to a valid file name."""
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = (
+            unicodedata.normalize("NFKD", value)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+        )
+    value = re.sub(r"[^\w\s]", "-", value.lower())
+    return re.sub(r"[-\s]+", "-", value).strip("-_")

package/meteocatpy/stations.py

@@ -0,0 +1,71 @@
+import aiohttp
+from .const import BASE_URL, STATIONS_LIST_URL
+from .exceptions import (
+    BadRequestError,
+    ForbiddenError,
+    TooManyRequestsError,
+    InternalServerError,
+    UnknownAPIError
+)
+
+class MeteocatStations:
+    """
+    Clase para interactuar con la API de Meteocat y obtener la lista de todas las estaciones."""
+
+    def __init__(self, api_key: str):
+        """
+        Inicializa la clase MeteocatStations.
+
+        Args:
+            api_key (str): Clave de API para autenticar las solicitudes.
+        """
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key": self.api_key,
+        }
+
+    async def get_stations(self):
+        """
+        Obtiene la lista de estaciones.
+
+        Returns:
+            dict: Lista de estaciones.
+        """
+        url = f"{BASE_URL}{STATIONS_LIST_URL}"
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(url, headers=self.headers) as response:
+                    if response.status == 200:
+                        return await response.json()
+
+                    # Gestionar errores según el código de estado
+                    if response.status == 400:
+                        raise BadRequestError(await response.json())
+                    elif response.status == 403:
+                        error_data = await response.json()
+                        if error_data.get("message") == "Forbidden":
+                            raise ForbiddenError(error_data)
+                        elif error_data.get("message") == "Missing Authentication Token":
+                            raise ForbiddenError(error_data)
+                    elif response.status == 429:
+                        raise TooManyRequestsError(await response.json())
+                    elif response.status == 500:
+                        raise InternalServerError(await response.json())
+                    else:
+                        raise UnknownAPIError(
+                            f"Unexpected error {response.status}: {await response.text()}"
+                        )
+
+            except aiohttp.ClientError as e:
+                raise UnknownAPIError(
+                    message=f"Error al conectar con la API de Meteocat: {str(e)}",
+                    status_code=0,
+                )
+
+            except Exception as ex:
+                raise UnknownAPIError(
+                    message=f"Error inesperado: {str(ex)}",
+                    status_code=0,
+                )
+

package/meteocatpy/symbols.py

@@ -0,0 +1,89 @@
+import aiohttp
+from .const import BASE_URL, SYMBOLS_URL
+from .exceptions import BadRequestError, ForbiddenError, TooManyRequestsError, InternalServerError, UnknownAPIError
+
+
+class MeteocatSymbols:
+    """Clase para interactuar con la API de símbolos de Meteocat."""
+
+    def __init__(self, api_key: str):
+        """
+        Inicializa la clase MeteocatSymbols.
+
+        Args:
+            api_key (str): Clave de API para autenticar las solicitudes.
+        """
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key": self.api_key,
+        }
+        self.symbols_map = {}
+
+    async def fetch_symbols(self):
+        url = f"{BASE_URL}{SYMBOLS_URL}"
+        async with aiohttp.ClientSession() as session:
+            try:
+                async with session.get(url, headers=self.headers) as response:
+                    if response.status == 200:
+                        data = await response.json()
+                        print(data)  # Esto te mostrará la estructura completa en la consola
+
+                        # Asegurarse de que `data` sea una lista de categorías
+                        if isinstance(data, list):
+                            self.symbols_map = {}
+                            for category in data:
+                                if "valors" in category:
+                                    # Guardamos los valores de cada categoría
+                                    self.symbols_map[category["nom"]] = category["valors"]
+                            return data  # Devolvemos todo el conjunto de datos
+
+                        else:
+                            raise UnknownAPIError(f"Unexpected structure of data: {data}", status_code=response.status)
+
+                    # Gestionar errores de respuesta
+                    if response.status == 400:
+                        raise BadRequestError(await response.json())
+                    elif response.status == 403:
+                        error_data = await response.json()
+                        if error_data.get("message") == "Forbidden":
+                            raise ForbiddenError(error_data)
+                        elif error_data.get("message") == "Missing Authentication Token":
+                            raise ForbiddenError(error_data)
+                    elif response.status == 429:
+                        raise TooManyRequestsError(await response.json())
+                    elif response.status == 500:
+                        raise InternalServerError(await response.json())
+                    else:
+                        raise UnknownAPIError(f"Unexpected error {response.status}: {await response.text()}", status_code=response.status)
+
+            except aiohttp.ClientError as e:
+                raise UnknownAPIError(
+                    message=f"Error al conectar con la API de Meteocat: {str(e)}",
+                    status_code=0,
+                )
+
+            except Exception as ex:
+                raise UnknownAPIError(
+                    message=f"Error inesperado: {str(ex)}",
+                    status_code=0,
+                )
+
+
+
+    def get_description(self, category: str, code: int) -> str:
+        """
+        Obtiene la descripción de un código de símbolo dentro de una categoría.
+
+        Args:
+            category (str): Nombre de la categoría (e.g., "cel").
+            code (int): Código del símbolo.
+
+        Returns:
+            str: Descripción del símbolo. Retorna 'Desconocido' si el código no está en el mapeo.
+        """
+        category_symbols = self.symbols_map.get(category, [])
+        for symbol in category_symbols:
+            if symbol["codi"] == str(code):  # El código es devuelto como string por la API
+                return symbol["descripcio"]
+        return "Desconocido"