meteo-lt-pkg 0.5.0__tar.gz → 0.5.1__tar.gz

{meteo_lt_pkg-0.5.0 → meteo_lt_pkg-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meteo_lt-pkg
-Version: 0.5.0
+Version: 0.5.1
 Summary: A library to fetch weather data from api.meteo.lt
 Author-email: Brunas <brunonas@gmail.com>
 Project-URL: Homepage, https://github.com/Brunas/meteo_lt-pkg
@@ -12,17 +12,17 @@ Classifier: Development Status :: 4 - Beta
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp
+Requires-Dist: aiohttp>=3.13
 Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: pyflakes; extra == "dev"
-Requires-Dist: pylint; extra == "dev"
-Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: black>=26.0; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"
+Requires-Dist: pyflakes>=3.0; extra == "dev"
+Requires-Dist: pylint>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
 Dynamic: license-file
 
 # Meteo.Lt Lithuanian weather forecast package
@@ -310,6 +310,136 @@ warning = WeatherWarning(
 print(f"Warning for {warning.county}: {warning.description}")
 ```
 
+### HydroStation
+
+Represents a hydrological observation station with water body information.
+
+```python
+from meteo_lt import HydroStation
+
+station = HydroStation(
+    code="klaipedos-juru-uosto-vms",
+    name="Klaipėdos jūrų uosto VMS",
+    water_body="Baltijos jūra",
+    coordinates=coords
+)
+print(f"Station: {station.name} on {station.water_body}")
+```
+
+### HydroObservation
+
+Represents a single hydrological observation with water measurements.
+
+```python
+from meteo_lt import HydroObservation
+
+observation = HydroObservation(
+    observation_datetime="2024-07-23T12:00:00+00:00",
+    water_level=481.8,
+    water_temperature=15.5,
+    water_discharge=100.0
+)
+print(f"Water level: {observation.water_level} cm")
+print(f"Water temperature: {observation.water_temperature}°C")
+```
+
+### HydroObservationData
+
+Represents a collection of hydrological observations for a specific station.
+
+```python
+from meteo_lt import HydroObservationData
+
+data = HydroObservationData(
+    station=station,
+    observations=[observation],
+    observations_data_range={"from": "2024-07-01", "to": "2024-07-23"}
+)
+print(f"Station: {data.station.name}")
+print(f"Observations: {len(data.observations)}")
+```
+
+## Hydrological Data
+
+The package provides access to hydrological data from Lithuanian water monitoring stations.
+
+### Fetching Hydrological Stations
+
+To get the list of all hydrological stations:
+
+```python
+async def fetch_hydro_stations():
+    async with MeteoLtAPI() as api:
+        stations = await api.get_hydro_stations()
+        for station in stations:
+            print(f"{station.name} ({station.code}) - Water body: {station.water_body}")
+
+asyncio.run(fetch_hydro_stations())
+```
+
+### Finding the Nearest Hydrological Station
+
+You can find the nearest hydrological station using coordinates:
+
+```python
+async def find_nearest_hydro_station():
+    async with MeteoLtAPI() as api:
+        # Example coordinates for Klaipėda, Lithuania
+        nearest_station = await api.get_nearest_hydro_station(55.6872, 21.2797)
+        print(f"Nearest station: {nearest_station.name}")
+        print(f"Water body: {nearest_station.water_body}")
+        print(f"Distance: approximately {nearest_station.latitude}, {nearest_station.longitude}")
+
+asyncio.run(find_nearest_hydro_station())
+```
+
+### Fetching Hydrological Observations
+
+To get water level and temperature observations for a specific station:
+
+```python
+async def fetch_hydro_observations():
+    async with MeteoLtAPI() as api:
+        # Get observations for a station
+        hydro_data = await api.get_hydro_observation_data("klaipedos-juru-uosto-vms")
+
+        print(f"Station: {hydro_data.station.name}")
+        print(f"Water body: {hydro_data.station.water_body}")
+        print(f"\nRecent observations:")
+
+        for observation in hydro_data.observations[:5]:
+            print(f"  {observation.observation_datetime}")
+            print(f"    Water level: {observation.water_level} cm")
+            print(f"    Water temperature: {observation.water_temperature}°C")
+            if observation.water_discharge:
+                print(f"    Water discharge: {observation.water_discharge} m³/s")
+
+asyncio.run(fetch_hydro_observations())
+```
+
+### Getting Observations for Nearest Station
+
+Combine location finding with observation fetching:
+
+```python
+async def get_nearest_station_observations():
+    async with MeteoLtAPI() as api:
+        # Find nearest hydro station to coordinates
+        nearest_station = await api.get_nearest_hydro_station(55.6872, 21.2797)
+
+        # Get observations for the nearest station
+        hydro_data = await api.get_hydro_observation_data(nearest_station.code)
+
+        print(f"Latest observations from {hydro_data.station.name}:")
+        if hydro_data.observations:
+            latest = hydro_data.observations[0]
+            print(f"  Time: {latest.observation_datetime}")
+            print(f"  Water level: {latest.water_level} cm")
+            print(f"  Temperature: {latest.water_temperature}°C")
+
+asyncio.run(get_nearest_station_observations())
+```
+
 ## Contributing
 
 Contributions are welcome! For major changes please open an issue to discuss or submit a pull request with your changes. If you want to contribute you can use devcontainers in vscode for easiest setup follow [instructions here](.devcontainer/README.md).

meteo_lt_pkg-0.5.0/meteo_lt_pkg.egg-info/PKG-INFO → meteo_lt_pkg-0.5.1/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: meteo_lt-pkg
-Version: 0.5.0
-Summary: A library to fetch weather data from api.meteo.lt
-Author-email: Brunas <brunonas@gmail.com>
-Project-URL: Homepage, https://github.com/Brunas/meteo_lt-pkg
-Project-URL: Issues, https://github.com/Brunas/meteo_lt-pkg/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: pyflakes; extra == "dev"
-Requires-Dist: pylint; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Dynamic: license-file
-
 # Meteo.Lt Lithuanian weather forecast package
 
 [![GitHub Release][releases-shield]][releases]
@@ -310,6 +283,136 @@ warning = WeatherWarning(
 print(f"Warning for {warning.county}: {warning.description}")
 ```
 
+### HydroStation
+
+Represents a hydrological observation station with water body information.
+
+```python
+from meteo_lt import HydroStation
+
+station = HydroStation(
+    code="klaipedos-juru-uosto-vms",
+    name="Klaipėdos jūrų uosto VMS",
+    water_body="Baltijos jūra",
+    coordinates=coords
+)
+print(f"Station: {station.name} on {station.water_body}")
+```
+
+### HydroObservation
+
+Represents a single hydrological observation with water measurements.
+
+```python
+from meteo_lt import HydroObservation
+
+observation = HydroObservation(
+    observation_datetime="2024-07-23T12:00:00+00:00",
+    water_level=481.8,
+    water_temperature=15.5,
+    water_discharge=100.0
+)
+print(f"Water level: {observation.water_level} cm")
+print(f"Water temperature: {observation.water_temperature}°C")
+```
+
+### HydroObservationData
+
+Represents a collection of hydrological observations for a specific station.
+
+```python
+from meteo_lt import HydroObservationData
+
+data = HydroObservationData(
+    station=station,
+    observations=[observation],
+    observations_data_range={"from": "2024-07-01", "to": "2024-07-23"}
+)
+print(f"Station: {data.station.name}")
+print(f"Observations: {len(data.observations)}")
+```
+
+## Hydrological Data
+
+The package provides access to hydrological data from Lithuanian water monitoring stations.
+
+### Fetching Hydrological Stations
+
+To get the list of all hydrological stations:
+
+```python
+async def fetch_hydro_stations():
+    async with MeteoLtAPI() as api:
+        stations = await api.get_hydro_stations()
+        for station in stations:
+            print(f"{station.name} ({station.code}) - Water body: {station.water_body}")
+
+asyncio.run(fetch_hydro_stations())
+```
+
+### Finding the Nearest Hydrological Station
+
+You can find the nearest hydrological station using coordinates:
+
+```python
+async def find_nearest_hydro_station():
+    async with MeteoLtAPI() as api:
+        # Example coordinates for Klaipėda, Lithuania
+        nearest_station = await api.get_nearest_hydro_station(55.6872, 21.2797)
+        print(f"Nearest station: {nearest_station.name}")
+        print(f"Water body: {nearest_station.water_body}")
+        print(f"Distance: approximately {nearest_station.latitude}, {nearest_station.longitude}")
+
+asyncio.run(find_nearest_hydro_station())
+```
+
+### Fetching Hydrological Observations
+
+To get water level and temperature observations for a specific station:
+
+```python
+async def fetch_hydro_observations():
+    async with MeteoLtAPI() as api:
+        # Get observations for a station
+        hydro_data = await api.get_hydro_observation_data("klaipedos-juru-uosto-vms")
+
+        print(f"Station: {hydro_data.station.name}")
+        print(f"Water body: {hydro_data.station.water_body}")
+        print(f"\nRecent observations:")
+
+        for observation in hydro_data.observations[:5]:
+            print(f"  {observation.observation_datetime}")
+            print(f"    Water level: {observation.water_level} cm")
+            print(f"    Water temperature: {observation.water_temperature}°C")
+            if observation.water_discharge:
+                print(f"    Water discharge: {observation.water_discharge} m³/s")
+
+asyncio.run(fetch_hydro_observations())
+```
+
+### Getting Observations for Nearest Station
+
+Combine location finding with observation fetching:
+
+```python
+async def get_nearest_station_observations():
+    async with MeteoLtAPI() as api:
+        # Find nearest hydro station to coordinates
+        nearest_station = await api.get_nearest_hydro_station(55.6872, 21.2797)
+
+        # Get observations for the nearest station
+        hydro_data = await api.get_hydro_observation_data(nearest_station.code)
+
+        print(f"Latest observations from {hydro_data.station.name}:")
+        if hydro_data.observations:
+            latest = hydro_data.observations[0]
+            print(f"  Time: {latest.observation_datetime}")
+            print(f"  Water level: {latest.water_level} cm")
+            print(f"  Temperature: {latest.water_temperature}°C")
+
+asyncio.run(get_nearest_station_observations())
+```
+
 ## Contributing
 
 Contributions are welcome! For major changes please open an issue to discuss or submit a pull request with your changes. If you want to contribute you can use devcontainers in vscode for easiest setup follow [instructions here](.devcontainer/README.md).
@@ -321,4 +424,4 @@ Contributions are welcome! For major changes please open an issue to discuss or
 [license-shield]: https://img.shields.io/github/license/Brunas/meteo_lt-pkg.svg?style=flat-square
 [maintenance-shield]: https://img.shields.io/badge/maintainer-Brunas%20%40Brunas-blue.svg?style=flat-square
 [releases-shield]: https://img.shields.io/github/release/Brunas/meteo_lt-pkg.svg?style=flat-square
-[releases]: https://github.com/Brunas/meteo_lt-pkg/releases
+[releases]: https://github.com/Brunas/meteo_lt-pkg/releases

meteo_lt_pkg-0.5.1/meteo_lt/__init__.py

@@ -0,0 +1,27 @@
+"""init.py"""
+
+from .api import MeteoLtAPI
+from .models import (
+    Coordinates,
+    LocationBase,
+    Place,
+    ForecastTimestamp,
+    Forecast,
+    WeatherWarning,
+    HydroStation,
+    HydroObservation,
+    HydroObservationData,
+)
+
+__all__ = [
+    "MeteoLtAPI",
+    "Coordinates",
+    "LocationBase",
+    "Place",
+    "ForecastTimestamp",
+    "Forecast",
+    "WeatherWarning",
+    "HydroStation",
+    "HydroObservation",
+    "HydroObservationData",
+]

meteo_lt_pkg-0.5.1/meteo_lt/api.py

@@ -0,0 +1,109 @@
+"""Main API class script"""
+
+from typing import List, Optional
+
+from .models import (
+    Forecast,
+    Place,
+    WeatherWarning,
+    HydroStation,
+    HydroObservationData,
+)
+from .utils import find_nearest_location
+from .client import MeteoLtClient
+from .warnings import WeatherWarningsProcessor
+
+
+class MeteoLtAPI:
+    """Main API class that orchestrates external API calls and warning processing"""
+
+    def __init__(self, session=None):
+        self.places = []
+        self.client = MeteoLtClient(session)
+        self.warnings_processor = WeatherWarningsProcessor(self.client)
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        await self.client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[Exception],
+        exc_tb: Optional[object],
+    ) -> None:
+        """Async context manager exit"""
+        await self.client.__aexit__(exc_type, exc_val, exc_tb)
+
+    async def close(self):
+        """Close the API client and cleanup resources"""
+        await self.client.close()
+
+    async def fetch_places(self) -> None:
+        """Gets all places from API"""
+        self.places = await self.client.fetch_places()
+
+    async def get_nearest_place(self, latitude: float, longitude: float) -> Optional[Place]:
+        """Finds nearest place using provided coordinates"""
+        if not self.places:
+            await self.fetch_places()
+        return find_nearest_location(latitude, longitude, self.places)
+
+    async def get_forecast_with_warnings(
+        self,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+        place_code: Optional[str] = None,
+    ) -> Forecast:
+        """Get forecast with weather warnings for a location"""
+        if place_code is None:
+            if latitude is None or longitude is None:
+                raise ValueError("Either place_code or both latitude and longitude must be provided")
+            place = await self.get_nearest_place(latitude, longitude)
+            place_code = place.code
+
+        return await self.get_forecast(place_code, include_warnings=True)
+
+    async def get_forecast(self, place_code: str, include_warnings: bool = True) -> Forecast:
+        """Retrieves forecast data from API"""
+        forecast = await self.client.fetch_forecast(place_code)
+
+        if include_warnings:
+            await self._enrich_forecast_with_warnings(forecast)
+
+        return forecast
+
+    async def get_weather_warnings(self, administrative_division: str = None) -> List[WeatherWarning]:
+        """Fetches weather warnings from meteo.lt JSON API"""
+        return await self.warnings_processor.get_weather_warnings(administrative_division)
+
+    async def _enrich_forecast_with_warnings(self, forecast: Forecast) -> None:
+        """Enrich forecast timestamps with relevant weather warnings"""
+        if not forecast or not forecast.place or not forecast.place.administrative_division:
+            return
+
+        warnings = await self.get_weather_warnings(forecast.place.administrative_division)
+
+        if warnings:
+            self.warnings_processor.enrich_forecast_with_warnings(forecast, warnings)
+
+    async def get_hydro_stations(self) -> List[HydroStation]:
+        """Get list of all hydrological stations"""
+        return await self.client.fetch_hydro_stations()
+
+    async def get_nearest_hydro_station(self, latitude: float, longitude: float) -> Optional[HydroStation]:
+        """Find the nearest hydrological station to given coordinates"""
+        stations = await self.get_hydro_stations()
+        if not stations:
+            return None
+        return find_nearest_location(latitude, longitude, stations)
+
+    async def get_hydro_observation_data(
+        self,
+        station_code: str,
+        observation_type: str = "measured",
+        date: str = "latest",
+    ) -> HydroObservationData:
+        """Get hydrological observation data for a station"""
+        return await self.client.fetch_hydro_observation_data(station_code, observation_type, date)

meteo_lt_pkg-0.5.1/meteo_lt/client.py

@@ -0,0 +1,138 @@
+"""MeteoLt API client for external API calls"""
+
+import json
+from typing import List, Optional, Dict, Any
+
+import aiohttp
+
+from .models import (
+    Place,
+    Forecast,
+    HydroStation,
+    HydroObservationData,
+    HydroObservation,
+)
+from .const import BASE_URL, WARNINGS_URL, TIMEOUT, ENCODING
+
+
+class MeteoLtClient:
+    """Client for external API calls to meteo.lt"""
+
+    def __init__(self, session: Optional[aiohttp.ClientSession] = None):
+        self._session = session
+        self._owns_session = session is None
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        if self._session is None:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=TIMEOUT),
+                raise_for_status=True,
+            )
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[Exception],
+        exc_tb: Optional[Any],
+    ) -> None:
+        """Async context manager exit"""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the client session if we own it"""
+        if self._session and self._owns_session:
+            await self._session.close()
+            self._session = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create a session"""
+        if self._session is None:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=TIMEOUT),
+                raise_for_status=True,
+            )
+        return self._session
+
+    async def fetch_places(self) -> List[Place]:
+        """Gets all places from API"""
+        session = await self._get_session()
+        async with session.get(f"{BASE_URL}/places") as response:
+            response.encoding = ENCODING
+            response_json = await response.json()
+            return [Place.from_dict(place) for place in response_json]
+
+    async def fetch_forecast(self, place_code: str) -> Forecast:
+        """Retrieves forecast data from API"""
+        session = await self._get_session()
+        async with session.get(f"{BASE_URL}/places/{place_code}/forecasts/long-term") as response:
+            response.encoding = ENCODING
+            response_json = await response.json()
+            return Forecast.from_dict(response_json)
+
+    async def fetch_weather_warnings(self) -> Dict[str, Any]:
+        """Fetches raw weather warnings data from meteo.lt JSON API"""
+        session = await self._get_session()
+
+        # Get the latest warnings file
+        async with session.get(WARNINGS_URL) as response:
+            file_list = await response.json()
+
+        if not file_list:
+            return []
+
+        # Fetch the latest warnings data
+        latest_file_url = file_list[0]  # First file is the most recent
+        async with session.get(latest_file_url) as response:
+            text_data = await response.text()
+            return json.loads(text_data)
+
+    async def fetch_hydro_stations(self) -> List[HydroStation]:
+        """Get list of all hydrological stations."""
+        session = await self._get_session()
+        async with session.get(f"{BASE_URL}/hydro-stations") as resp:
+            if resp.status == 200:
+                resp.encoding = ENCODING
+                response = await resp.json()
+                stations = []
+                for station_data in response:
+                    stations.append(HydroStation.from_dict(station_data))
+                return stations
+            raise aiohttp.ClientError(f"API returned status {resp.status}")
+
+    async def fetch_hydro_station(self, station_code: str) -> HydroStation:
+        """Get information about a specific hydrological station."""
+        session = await self._get_session()
+        async with session.get(f"{BASE_URL}/hydro-stations/{station_code}") as resp:
+            if resp.status == 200:
+                resp.encoding = ENCODING
+                response = await resp.json()
+                return HydroStation.from_dict(response)
+            raise aiohttp.ClientError(f"API returned status {resp.status}")
+
+    async def fetch_hydro_observation_data(
+        self,
+        station_code: str,
+        observation_type: str = "measured",
+        date: str = "latest",
+    ) -> HydroObservationData:
+        """Get hydrological observation data for a station."""
+        session = await self._get_session()
+        async with session.get(
+            f"{BASE_URL}/hydro-stations/{station_code}/observations/{observation_type}/{date}"
+        ) as resp:
+            if resp.status == 200:
+                response = await resp.json()
+                station = HydroStation.from_dict(response.get("station"))
+
+                observations = []
+                for obs_data in response.get("observations", []):
+                    observations.append(HydroObservation.from_dict(obs_data))
+
+                return HydroObservationData(
+                    station=station,
+                    observations_data_range=response.get("observationsDataRange"),
+                    observations=observations,
+                )
+            raise aiohttp.ClientError(f"API returned status {resp.status}")

{meteo_lt_pkg-0.5.0 → meteo_lt_pkg-0.5.1}/meteo_lt/const.py

@@ -1,10 +1,7 @@
 """const.py"""
 
 BASE_URL = "https://api.meteo.lt/v1"
-WARNINGS_URL = (
-    "https://www.meteo.lt/app/mu-plugins/Meteo/Components/"
-    "WeatherWarningsNew/list_JSON.php"
-)
+WARNINGS_URL = "https://www.meteo.lt/app/mu-plugins/Meteo/Components/" "WeatherWarningsNew/list_JSON.php"
 TIMEOUT = 30
 ENCODING = "utf-8"