meteostat 1.7.6__py3-none-any.whl → 2.0.1__py3-none-any.whl

meteostat/__init__.py

@@ -2,34 +2,53 @@
 █▀▄▀█ █▀▀ ▀█▀ █▀▀ █▀█ █▀ ▀█▀ ▄▀█ ▀█▀
 █░▀░█ ██▄ ░█░ ██▄ █▄█ ▄█ ░█░ █▀█ ░█░
 
-A Python library for accessing open weather and climate data
+A Python library for accessing open weather and climate data.
 
 Meteorological data provided by Meteostat (https://dev.meteostat.net)
-under the terms of the Creative Commons Attribution-NonCommercial
-4.0 International Public License.
+under the terms of the Creative Commons Attribution 4.0 International
+License.
 
 The code is licensed under the MIT license.
 """
 
 __appname__ = "meteostat"
-__version__ = "1.7.6"
+__version__ = "2.0.1"
 
-from .interface.base import Base
-from .interface.timeseries import TimeSeries
-from .interface.stations import Stations
-from .interface.point import Point
-from .interface.hourly import Hourly
-from .interface.daily import Daily
-from .interface.monthly import Monthly
-from .interface.normals import Normals
+from meteostat.api.daily import daily
+from meteostat.api.hourly import hourly
+from meteostat.api.interpolate import interpolate
+from meteostat.api.inventory import Inventory
+from meteostat.api.merge import merge
+from meteostat.api.monthly import monthly
+from meteostat.api.normals import normals
+from meteostat.api.point import Point
+from meteostat.api.stations import stations
+from meteostat.api.timeseries import TimeSeries
+from meteostat.core.cache import purge
+from meteostat.api.config import config
+from meteostat.enumerations import Granularity, Parameter, Provider, UnitSystem
+from meteostat.interpolation.lapserate import lapse_rate
+from meteostat.typing import Station, License
 
+# Export public API
 __all__ = [
-    "Base",
-    "TimeSeries",
-    "Stations",
+    "config",
+    "daily",
+    "hourly",
+    "Granularity",
+    "interpolate",
+    "Inventory",
+    "lapse_rate",
+    "License",
+    "merge",
+    "monthly",
+    "normals",
+    "Parameter",
     "Point",
-    "Hourly",
-    "Daily",
-    "Monthly",
-    "Normals",
+    "Provider",
+    "purge",
+    "Station",
+    "stations",
+    "TimeSeries",
+    "UnitSystem",
 ]

meteostat/api/config.py

@@ -0,0 +1,158 @@
+"""
+Configuration Service
+
+Manages configuration settings for Meteostat, including cache, network,
+stations, interpolation, and provider-specific settings. Configuration can be
+loaded from environment variables with the MS_ prefix.
+"""
+
+import os
+import json
+from typing import Any, List, Optional
+
+from meteostat.core.logger import logger
+from meteostat.enumerations import TTL, Parameter
+from meteostat.utils.types import extract_property_type, validate_parsed_value
+
+
+class ConfigService:
+    """
+    Configuration Service for Meteostat
+    """
+
+    prefix: str
+
+    @property
+    def _prefix(self) -> str:
+        """
+        The environment variable prefix
+        """
+        return f"{self.prefix}_" if self.prefix else ""
+
+    def _parse_env_value(self, key: str, value: str) -> Any:
+        """
+        Parse an environment variable value and validate against property type
+        """
+        # Extract the expected type for the property
+        expected_type, original_type = extract_property_type(self.__class__, key)
+
+        if expected_type is None:
+            # Fallback to JSON parsing if no type annotation is available
+            try:
+                return json.loads(value)
+            except (json.JSONDecodeError, TypeError, ValueError):
+                logger.error("Failed to parse environment variable '%s'", key)
+                return None
+
+        # Parse the value using JSON
+        try:
+            parsed_value = json.loads(value)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            logger.error("Failed to parse environment variable '%s'", key)
+            return None
+
+        # Validate and potentially convert the parsed value
+        return validate_parsed_value(parsed_value, expected_type, original_type, key)
+
+    def _set_env_value(self, key: str, value: Any) -> None:
+        """
+        Set a configuration using a key-value pair
+        """
+        setattr(self, key, value)
+
+    def __init__(self, prefix: str = "MS") -> None:
+        """
+        Initialize configuration service
+        """
+        self.prefix = prefix
+        self.load_env()
+
+    def get_env_name(self, key: str) -> str:
+        """
+        Get the environment variable name for a given key
+        """
+        if not hasattr(self, key):
+            raise KeyError(f"Configuration has no key '{key}'")
+
+        key = f"{self._prefix}{key}"
+        return key.upper()
+
+    def load_env(self) -> None:
+        """
+        Update configuration from environment variables with a given prefix.
+        """
+        for key, value in os.environ.items():
+            if not key.startswith(self._prefix):
+                continue
+
+            key = key.replace(self._prefix, "").lower()
+            value = self._parse_env_value(key, value)
+
+            if value is not None:
+                self._set_env_value(key, value)
+
+
+class Config(ConfigService):
+    """
+    Meteostat Configuration
+
+    Manages all configuration settings including cache, network, stations,
+    interpolation, and provider-specific settings. Supports loading configuration
+    from environment variables.
+    """
+
+    # General settings
+    block_large_requests: bool = True  # Block requests that include too many stations
+
+    # Cache settings
+    cache_enable: bool = True
+    cache_directory: str = (
+        os.path.expanduser("~") + os.sep + ".meteostat" + os.sep + "cache"
+    )
+    cache_ttl: int = TTL.MONTH
+    cache_autoclean: bool = True
+
+    # Network settings
+    network_proxies: Optional[dict] = None
+
+    # Station meta data settings
+    stations_db_ttl: int = TTL.WEEK
+    stations_db_endpoints: List[str] = [
+        "https://data.meteostat.net/stations.db",
+        "https://raw.githubusercontent.com/meteostat/weather-stations/master/stations.db",
+    ]
+    stations_db_file: str = (
+        os.path.expanduser("~") + os.sep + ".meteostat" + os.sep + "stations.db"
+    )
+
+    # Interpolation settings
+    lapse_rate_parameters = [Parameter.TEMP, Parameter.TMIN, Parameter.TMAX]
+
+    # [Provider] Meteostat settings
+    include_model_data: bool = True
+    hourly_endpoint: str = "https://data.meteostat.net/hourly/{year}/{station}.csv.gz"
+    daily_endpoint: str = "https://data.meteostat.net/daily/{year}/{station}.csv.gz"
+    monthly_endpoint: str = "https://data.meteostat.net/monthly/{station}.csv.gz"
+
+    # [Provider] DWD settings
+    dwd_ftp_host: str = "opendata.dwd.de"
+    dwd_hourly_modes: Optional[List[str]] = None
+    dwd_daily_modes: Optional[List[str]] = None
+    dwd_climat_modes: Optional[List[str]] = None
+
+    # [Provider] NOAA settings
+    aviationweather_endpoint: str = (
+        "https://aviationweather.gov/api/data/metar?"
+        "ids={station}&format=raw&taf=false&hours=24"
+    )
+    aviationweather_user_agent: Optional[str] = None
+
+    # [Provider] Met.no settings
+    metno_forecast_endpoint: str = (
+        "https://api.met.no/weatherapi/locationforecast/2.0/compact?"
+        "lat={latitude}&lon={longitude}&altitude={elevation}"
+    )
+    metno_user_agent: Optional[str] = None
+
+
+config = Config("MS")

meteostat/api/daily.py

@@ -0,0 +1,76 @@
+"""
+Daily Time Series Data
+
+Access daily time series data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+from datetime import datetime, date
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.typing import Station, Request
+from meteostat.api.point import Point
+from meteostat.utils.parsers import parse_station, parse_time
+
+DEFAULT_PARAMETERS = [
+    Parameter.TEMP,
+    Parameter.TMIN,
+    Parameter.TMAX,
+    Parameter.RHUM,
+    Parameter.PRCP,
+    Parameter.SNWD,
+    Parameter.WSPD,
+    Parameter.WPGT,
+    Parameter.PRES,
+    Parameter.TSUN,
+    Parameter.CLDC,
+]
+
+
+def daily(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: Optional[datetime | date],
+    end: Optional[datetime | date],
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+):
+    """
+    Access daily time series data.
+
+    Parameters
+    ----------
+    station : str, Station, Point, List[str | Station | Point], pd.Index, pd.Series
+        Weather station(s) or Point(s) to query data for. Can be a single station/point or a list.
+        Points are converted to virtual stations with IDs like $0001, $0002, etc.
+    start : datetime, date, optional
+        Start date for the data query. If None, the earliest available date will be used.
+    end : datetime, date, optional
+        End date for the data query. If None, the latest available date will be used.
+    parameters : List[Parameter], optional
+        List of parameters to include in the data query. Defaults to a set of common parameters.
+    providers : List[Provider], optional
+        List of data providers to use for the query. Defaults to the daily provider.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the daily data for the specified stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.DAILY]
+
+    req = Request(
+        granularity=Granularity.DAILY,
+        providers=providers,
+        parameters=parameters,
+        station=parse_station(station),
+        start=parse_time(start),
+        end=parse_time(end, is_end=True),
+    )
+
+    return data_service.fetch(req)

meteostat/api/hourly.py

@@ -0,0 +1,80 @@
+"""
+Hourly Time Series Data
+
+Access hourly time series data for one or multiple weather stations.
+"""
+
+from typing import List, Optional
+from datetime import datetime, date
+
+import pandas as pd
+
+from meteostat.core.data import data_service
+from meteostat.enumerations import Parameter, Provider, Granularity
+from meteostat.typing import Station, Request
+from meteostat.api.point import Point
+from meteostat.utils.parsers import parse_station, parse_time
+
+DEFAULT_PARAMETERS = [
+    Parameter.TEMP,
+    Parameter.RHUM,
+    Parameter.PRCP,
+    Parameter.SNWD,
+    Parameter.WDIR,
+    Parameter.WSPD,
+    Parameter.WPGT,
+    Parameter.PRES,
+    Parameter.TSUN,
+    Parameter.CLDC,
+    Parameter.COCO,
+]
+
+
+def hourly(
+    station: str | Station | Point | List[str | Station | Point] | pd.DataFrame,
+    start: Optional[datetime | date],
+    end: Optional[datetime | date],
+    timezone: Optional[str] = None,
+    parameters: Optional[List[Parameter]] = None,
+    providers: Optional[List[Provider]] = None,
+):
+    """
+    Access hourly time series data.
+
+    Parameters
+    ----------
+    station : str, Station, Point, List[str | Station | Point], pd.Index, pd.Series
+        Weather station(s) or Point(s) to query data for. Can be a single station/point or a list.
+        Points are converted to virtual stations with IDs like $0001, $0002, etc.
+    start : datetime, date, optional
+        Start date for the data query. If None, the earliest available date will be used.
+    end : datetime, date, optional
+        End date for the data query. If None, the latest available date will be used.
+    timezone : str, optional
+        Time zone for the data query. If None, UTC will be used.
+    parameters : List[Parameter], optional
+        List of parameters to include in the data query. Defaults to a set of common parameters.
+    providers : List[Provider], optional
+        List of data providers to use for the query. Defaults to the hourly provider.
+
+    Returns
+    -------
+    TimeSeries
+        A TimeSeries object containing the hourly data for the specified stations and parameters.
+    """
+    if parameters is None:
+        parameters = DEFAULT_PARAMETERS
+    if providers is None:
+        providers = [Provider.HOURLY]
+
+    req = Request(
+        granularity=Granularity.HOURLY,
+        providers=providers,
+        parameters=parameters,
+        station=parse_station(station),
+        start=parse_time(start, timezone),
+        end=parse_time(end, timezone, is_end=True),
+        timezone=timezone,
+    )
+
+    return data_service.fetch(req)