open-data-bz-meteo 1.0.0__tar.gz

open_data_bz_meteo-1.0.0/LICENSE.md

@@ -0,0 +1,20 @@
+This work is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
+
+You are free to:
+
+- Share - copy and redistribute the material in any medium or format.
+- Adapt - remix, transform, and build upon the material.
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+Under the following terms:
+
+- Attribution - You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+- ShareAlike - If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
+
+No additional restrictions - You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+Disclaimer - The licensor makes no warranties about the material, and is not liable for any damages arising from its use.
+
+To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/.

open_data_bz_meteo-1.0.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: open_data_bz_meteo
+Version: 1.0.0
+Summary: Python API client for the open meteo data V1 service, provided by Provincia autonoma di Bolzano - Informatica Alto Adige SPA.
+Author-email: david vnl <io@davole.com>
+License-Expression: CC-BY-SA-4.0
+Project-URL: Homepage, https://github.com/dvdvnl/open_data_bz_meteo
+Project-URL: Issues, https://github.com/dvdvnl/open_data_bz_meteo/issues
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: requests>=2.28
+Requires-Dist: pydantic>=2.0
+Provides-Extra: develop
+Requires-Dist: build>=1.4.0; extra == "develop"
+Requires-Dist: pytest-cov>=7.0; extra == "develop"
+Requires-Dist: pytest>=7.0; extra == "develop"
+Requires-Dist: requests-mock>=1.9.3; extra == "develop"
+Requires-Dist: twine>=6.2.0; extra == "develop"
+Dynamic: license-file
+
+# Open Data BZ Meteo - API Client
+
+Python API client for the "Open Meteo Data V1" service, provided by _Provincia autonoma di Bolzano - Informatica Alto Adige SPA_. The API documentation can be found [here](https://data.civis.bz.it/dataset/misure-meteo-e-idrografiche).
+
+## Core classes
+
+### `Client`
+
+Main entrypoint to the API.
+
+- `get_stations()` fetches all stations and caches them on the client.
+- `get_station(station_code)` looks up a single station by code (refreshes cache).
+- `get_sensors(station)` fetches sensors for a given station.
+- `get_sensor(station, sensor_type)` fetches a single sensor and raises `ValueError` if not found.
+
+### `Station`
+
+- Represents a station with location data (`latitude`, `longitude`, `altitude`) and localized names (`name_deu`, `name_eng`, `name_ita`, `name_lld`).
+- `sensor_types`: sensor types available at this station.
+- `get_sensor(sensor_type)`: returns the first matching sensor or `None`.
+
+### `Sensor`
+
+- Represents a single sensor reading with `type`, `unit`, `value`, and `date`.
+- `parsed_datetime`: computed `datetime` parsed from the raw `date` string.
+- Localized description (`description_deu`, `description_ita`, `description_lld`).
+
+## Usage
+
+```python
+from open_data_bz_meteo import Client
+
+client = Client(timeout=5)
+
+# List available stations
+stations = client.get_stations()
+print(stations[0].name_eng, stations[0].latitude)
+
+# Fetch sensors for a single station
+station = stations[0]
+station.sensors = client.get_sensors(station)
+print([s.type for s in station.sensors])
+
+# Fetch a single sensor by type
+sensor = client.get_sensor(station, "WT")
+print(sensor.value, sensor.unit)
+```

open_data_bz_meteo-1.0.0/README.md

@@ -0,0 +1,47 @@
+# Open Data BZ Meteo - API Client
+
+Python API client for the "Open Meteo Data V1" service, provided by _Provincia autonoma di Bolzano - Informatica Alto Adige SPA_. The API documentation can be found [here](https://data.civis.bz.it/dataset/misure-meteo-e-idrografiche).
+
+## Core classes
+
+### `Client`
+
+Main entrypoint to the API.
+
+- `get_stations()` fetches all stations and caches them on the client.
+- `get_station(station_code)` looks up a single station by code (refreshes cache).
+- `get_sensors(station)` fetches sensors for a given station.
+- `get_sensor(station, sensor_type)` fetches a single sensor and raises `ValueError` if not found.
+
+### `Station`
+
+- Represents a station with location data (`latitude`, `longitude`, `altitude`) and localized names (`name_deu`, `name_eng`, `name_ita`, `name_lld`).
+- `sensor_types`: sensor types available at this station.
+- `get_sensor(sensor_type)`: returns the first matching sensor or `None`.
+
+### `Sensor`
+
+- Represents a single sensor reading with `type`, `unit`, `value`, and `date`.
+- `parsed_datetime`: computed `datetime` parsed from the raw `date` string.
+- Localized description (`description_deu`, `description_ita`, `description_lld`).
+
+## Usage
+
+```python
+from open_data_bz_meteo import Client
+
+client = Client(timeout=5)
+
+# List available stations
+stations = client.get_stations()
+print(stations[0].name_eng, stations[0].latitude)
+
+# Fetch sensors for a single station
+station = stations[0]
+station.sensors = client.get_sensors(station)
+print([s.type for s in station.sensors])
+
+# Fetch a single sensor by type
+sensor = client.get_sensor(station, "WT")
+print(sensor.value, sensor.unit)
+```

open_data_bz_meteo-1.0.0/open_data_bz_meteo/__init__.py

@@ -0,0 +1,7 @@
+"""Open Data BZ Meteo Client"""
+
+from .client import Client
+from .sensor import Sensor
+from .station import Station
+
+__all__ = ["Client", "Sensor", "Station"]

open_data_bz_meteo-1.0.0/open_data_bz_meteo/client.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import requests
+
+from open_data_bz_meteo.const import API_URL
+
+from .sensor import Sensor
+from .station import Station
+
+
+class Client:
+    def __init__(
+        self,
+        base_url: str = API_URL,
+        timeout: int = 10,
+        session: requests.Session | None = None,
+    ) -> None:
+        """Create a client.
+
+        Args:
+            base_url: Base URL of the Open Meteo Data service (no trailing slash).
+            timeout: Default request timeout in seconds.
+            session: Optional requests.Session for advanced usage / testing.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.session = session or requests.Session()
+        self.timeout = timeout
+
+        self.stations: list[Station] = []
+        self.sensors: list[Sensor] = []
+
+    # Get all stations
+    def get_stations(self) -> list[Station]:
+        """Fetch all stations from the API and cache them in `self.stations`.
+
+        Returns:
+            list[Station]: All stations returned by the service.
+        """
+
+        # GET request to the API
+        response = self.session.get(
+            f"{self.base_url}/stations",
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+
+        data = response.json().get("features", [])
+
+        # Rebuild station list to avoid duplicates
+        self.stations = []
+        for feature in data:
+            station_props = feature.get("properties", {})
+            self.stations.append(Station.model_validate(station_props))
+
+        return self.stations
+
+    # Get a single station
+    def get_station(self, station_code: str) -> Station | None:
+        """Return the station matching `station_code`, refreshing the station list.
+
+        Args:
+            station_code: The station code to look up.
+
+        Returns:
+            Optional[Station]: The matched station, or None if not found.
+        """
+
+        # Get all stations
+        self.get_stations()
+
+        # Loop through stations and return the station with the given station_code
+        for station in self.stations:
+            if station.station_code == station_code:
+                return station
+
+    # Get sensors from station
+    def get_sensors(self, station: Station) -> list[Sensor]:
+        """Fetch sensors for a specific station.
+
+        Args:
+            station: The station to fetch sensors for.
+
+        Returns:
+            list[Sensor]: Sensors belonging to the station.
+        """
+
+        sensors: list[Sensor] = []
+
+        # GET request to the API
+        response = self.session.get(
+            f"{self.base_url}/sensors",
+            params={"station_code": station.station_code},
+            timeout=self.timeout,
+        )
+
+        response.raise_for_status()
+
+        # Get the data from the response
+        data = response.json() or []
+
+        # Loop through data and create sensor objects via pydantic
+        for sensor_data in data:
+            sensors.append(Sensor.model_validate(sensor_data))
+
+        return sensors
+
+    # Get a single sensor from a station
+    def get_sensor(self, station: Station, sensor_type: str) -> Sensor:
+        """Fetch a single sensor by type for a station.
+
+        Args:
+            station: The station to query.
+            sensor_type: The sensor type code to retrieve.
+
+        Raises:
+            ValueError: If no sensor with the given type exists for the station.
+
+        Returns:
+            Sensor: The requested sensor.
+        """
+
+        # GET request to the API
+        response = self.session.get(
+            f"{self.base_url}/sensors",
+            params={"station_code": station.station_code, "sensor_code": sensor_type},
+            timeout=self.timeout,
+        )
+
+        response.raise_for_status()
+
+        data = response.json() or []
+        if not data:
+            raise ValueError(
+                f"No sensor found with type '{sensor_type}' for station '{station.station_code}'"
+            )
+
+        return Sensor.model_validate(data[0])

open_data_bz_meteo-1.0.0/open_data_bz_meteo/const.py

@@ -0,0 +1,2 @@
+DATE_FORMAT = "%Y-%m-%dT%H:%M:%S%Z"
+API_URL = "https://geoservices.buergernetz.bz.it/services/meteo/v1"

open_data_bz_meteo-1.0.0/open_data_bz_meteo/sensor.py

@@ -0,0 +1,29 @@
+import datetime
+
+from pydantic import BaseModel, Field, computed_field
+
+from .const import DATE_FORMAT
+
+
+class Sensor(BaseModel):
+    """Represents a single sensor reading from the Open Meteo Data API.
+
+    This model is created from API response records and provides a
+    computed ``parsed_datetime`` property for easy datetime access.
+    """
+
+    date: str = Field(..., alias="DATE")
+    description_deu: str = Field(..., alias="DESC_D")
+    description_ita: str = Field(..., alias="DESC_I")
+    description_lld: str = Field(..., alias="DESC_L")
+    station_code: str = Field(..., alias="SCODE")
+    type: str = Field(..., alias="TYPE")
+    unit: str = Field(..., alias="UNIT")
+    value: str | float = Field(..., alias="VALUE")
+
+    @computed_field
+    def parsed_datetime(self) -> "datetime.datetime":
+        """Parsed :class:`datetime.datetime` from the raw ``date`` string."""
+        return datetime.datetime.strptime(self.date, DATE_FORMAT).replace(
+            tzinfo=datetime.UTC
+        )

open_data_bz_meteo-1.0.0/open_data_bz_meteo/station.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, Field, computed_field
+
+from .sensor import Sensor
+
+
+class Station(BaseModel):
+    """Represents a meteorological station in the Open Meteo Data API.
+
+    This model includes location data, localized station names, and an optional
+    list of sensors that can be populated via the API client.
+    """
+
+    altitude: float = Field(..., alias="ALT")
+    latitude: float = Field(..., alias="LAT")
+    longitude: float = Field(..., alias="LONG")
+    name_deu: str | None = Field(..., alias="NAME_D")
+    name_eng: str | None = Field(..., alias="NAME_E")
+    name_ita: str | None = Field(..., alias="NAME_I")
+    name_lld: str | None = Field(..., alias="NAME_L")
+    sensors: list[Sensor] = Field(default_factory=list)
+    station_code: str = Field(..., alias="SCODE")
+
+    @computed_field
+    def sensor_types(self) -> list[str]:
+        """Return a list of sensor types available at this station."""
+        return [sensor.type for sensor in self.sensors] if self.sensors else []
+
+    def get_sensor(self, sensor_type: str) -> Sensor | None:
+        """Return the first sensor matching `sensor_type`, or `None` if not found."""
+        for sensor in self.sensors:
+            if sensor.type == sensor_type:
+                return sensor

open_data_bz_meteo-1.0.0/open_data_bz_meteo.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: open_data_bz_meteo
+Version: 1.0.0
+Summary: Python API client for the open meteo data V1 service, provided by Provincia autonoma di Bolzano - Informatica Alto Adige SPA.
+Author-email: david vnl <io@davole.com>
+License-Expression: CC-BY-SA-4.0
+Project-URL: Homepage, https://github.com/dvdvnl/open_data_bz_meteo
+Project-URL: Issues, https://github.com/dvdvnl/open_data_bz_meteo/issues
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: requests>=2.28
+Requires-Dist: pydantic>=2.0
+Provides-Extra: develop
+Requires-Dist: build>=1.4.0; extra == "develop"
+Requires-Dist: pytest-cov>=7.0; extra == "develop"
+Requires-Dist: pytest>=7.0; extra == "develop"
+Requires-Dist: requests-mock>=1.9.3; extra == "develop"
+Requires-Dist: twine>=6.2.0; extra == "develop"
+Dynamic: license-file
+
+# Open Data BZ Meteo - API Client
+
+Python API client for the "Open Meteo Data V1" service, provided by _Provincia autonoma di Bolzano - Informatica Alto Adige SPA_. The API documentation can be found [here](https://data.civis.bz.it/dataset/misure-meteo-e-idrografiche).
+
+## Core classes
+
+### `Client`
+
+Main entrypoint to the API.
+
+- `get_stations()` fetches all stations and caches them on the client.
+- `get_station(station_code)` looks up a single station by code (refreshes cache).
+- `get_sensors(station)` fetches sensors for a given station.
+- `get_sensor(station, sensor_type)` fetches a single sensor and raises `ValueError` if not found.
+
+### `Station`
+
+- Represents a station with location data (`latitude`, `longitude`, `altitude`) and localized names (`name_deu`, `name_eng`, `name_ita`, `name_lld`).
+- `sensor_types`: sensor types available at this station.
+- `get_sensor(sensor_type)`: returns the first matching sensor or `None`.
+
+### `Sensor`
+
+- Represents a single sensor reading with `type`, `unit`, `value`, and `date`.
+- `parsed_datetime`: computed `datetime` parsed from the raw `date` string.
+- Localized description (`description_deu`, `description_ita`, `description_lld`).
+
+## Usage
+
+```python
+from open_data_bz_meteo import Client
+
+client = Client(timeout=5)
+
+# List available stations
+stations = client.get_stations()
+print(stations[0].name_eng, stations[0].latitude)
+
+# Fetch sensors for a single station
+station = stations[0]
+station.sensors = client.get_sensors(station)
+print([s.type for s in station.sensors])
+
+# Fetch a single sensor by type
+sensor = client.get_sensor(station, "WT")
+print(sensor.value, sensor.unit)
+```

open_data_bz_meteo-1.0.0/open_data_bz_meteo.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE.md
+README.md
+pyproject.toml
+open_data_bz_meteo/__init__.py
+open_data_bz_meteo/client.py
+open_data_bz_meteo/const.py
+open_data_bz_meteo/sensor.py
+open_data_bz_meteo/station.py
+open_data_bz_meteo.egg-info/PKG-INFO
+open_data_bz_meteo.egg-info/SOURCES.txt
+open_data_bz_meteo.egg-info/dependency_links.txt
+open_data_bz_meteo.egg-info/requires.txt
+open_data_bz_meteo.egg-info/top_level.txt

open_data_bz_meteo-1.0.0/open_data_bz_meteo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

open_data_bz_meteo-1.0.0/open_data_bz_meteo.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.28
+pydantic>=2.0
+
+[develop]
+build>=1.4.0
+pytest-cov>=7.0
+pytest>=7.0
+requests-mock>=1.9.3
+twine>=6.2.0

open_data_bz_meteo-1.0.0/open_data_bz_meteo.egg-info/top_level.txt

@@ -0,0 +1 @@
+open_data_bz_meteo

open_data_bz_meteo-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "open_data_bz_meteo"
+version = "1.0.0"
+authors = [
+  { name="david vnl", email="io@davole.com" },
+]
+description = "Python API client for the open meteo data V1 service, provided by Provincia autonoma di Bolzano - Informatica Alto Adige SPA."
+readme = "README.md"
+license = "CC-BY-SA-4.0"
+requires-python = ">=3.12.0"
+dependencies = [
+    "requests>=2.28",
+    "pydantic>=2.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.12"
+]
+
+[build-system]
+requires = ["setuptools>=65", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Optional groups for development and testing
+[project.optional-dependencies]
+develop = [
+    "build>=1.4.0",
+    "pytest-cov>=7.0",
+    "pytest>=7.0",
+    "requests-mock>=1.9.3",
+    "twine>=6.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dvdvnl/open_data_bz_meteo"
+Issues = "https://github.com/dvdvnl/open_data_bz_meteo/issues"
+
+[tool.pytest.ini_options]
+addopts = "--cov=open_data_bz_meteo --cov-config=.coveragerc -q"
+python_files = "tests/**/*.py"
+

open_data_bz_meteo-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+