meteostat 1.7.6__tar.gz → 2.0.1__tar.gz

meteostat-2.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: meteostat
+Version: 2.0.1
+Summary: Access and analyze historical weather and climate data with Python.
+License-File: LICENSE
+Author: Meteostat
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: pytz (>=2023.3.post1,<2024.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+<!-- PROJECT SHIELDS -->
+<div align="center">
+  
+  [![Downloads][downloads-shield]][downloads-url]
+  [![Provider Tests][provider-tests-shield]][provider-tests-url]
+  [![Issues][issues-shield]][issues-url]
+  [![MIT License][license-shield]][license-url]
+  [![Stargazers][stars-shield]][stars-url]
+  
+</div>
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/meteostat/meteostat">
+    <img src="https://media.meteostat.net/icon.svg" alt="Meteostat Logo" width="80" height="80">
+  </a>
+
+  <h3 align="center">Meteostat Python Package</h3>
+
+  <p align="center">
+    Access and analyze historical weather and climate data with Python.
+    <p>
+      <a href="https://dev.meteostat.net/python"><strong>Explore the docs »</strong></a>
+    </p>
+    <p>
+      <a href="https://meteostat.net">Visit Website</a>
+      &middot;
+      <a href="https://github.com/meteostat/meteostat/issues">Report Bug</a>
+      &middot;
+      <a href="https://github.com/orgs/meteostat/discussions">Request Feature</a>
+    </p>
+  </p>
+</div>
+
+## 📚 Installation
+
+The Meteostat Python package is available through [PyPI](https://pypi.org/project/meteostat/):
+
+```sh
+pip install meteostat
+```
+
+## 🚀 Usage
+
+Let's plot 2018 temperature data for Frankfurt, Germany:
+
+```python
+from datetime import date
+import matplotlib.pyplot as plt
+import meteostat as ms
+
+# Specify location and time range
+POINT = ms.Point(50.1155, 8.6842, 113)  # Try with your location
+START = date(2018, 1, 1)
+END = date(2018, 12, 31)
+
+# Get nearby weather stations
+stations = ms.stations.nearby(POINT, limit=4)
+
+# Get daily data & perform interpolation
+ts = ms.daily(stations, START, END)
+df = ms.interpolate(ts, POINT).fetch()
+
+# Plot line chart including average, minimum and maximum temperature
+df.plot(y=[ms.Parameter.TEMP, ms.Parameter.TMIN, ms.Parameter.TMAX])
+plt.show()
+```
+
+Take a look at the expected output:
+
+![2018 temperature data for Frankfurt, Germany][product-screenshot]
+
+## 🤝 Contributing
+
+Please read our [contributing guidelines](https://dev.meteostat.net/python/contributing) for details on how to contribute to the Meteostat Python library.
+
+**Top contributors**
+
+<a href="https://github.com/meteostat/meteostat/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=meteostat/meteostat" alt="Meteostat Contributors" />
+</a>
+
+## 🌟 Featured In
+
+Meteostat has been featured and used by various media outlets and organizations, including:
+
+- [Towards Data Science](https://towardsdatascience.com/get-temperature-data-by-location-with-python-52ed872dd621/)
+- [ZEIT ONLINE](https://www.zeit.de/digital/internet/2022-03/desinformation-russland-ukraine-fotos-fake-news-falschinformation-echtheit)
+- [Deutsche Presse-Agentur (dpa)](https://dpa-factchecking.com/germany/230103-99-92282/)
+- [heise online](https://www.heise.de/news/Open-Source-Projekt-zu-Klimadaten-Meteostat-Python-Library-1-0-erschienen-4985015.html)
+
+Join the growing community of users and researchers relying on Meteostat for their weather data needs.
+
+## 📄 License
+
+Meteostat is licensed under the [**MIT License**](https://github.com/meteostat/meteostat/blob/main/LICENSE). Data provided by Meteostat is generally licensed under the [**Creative Commons Attribution 4.0 International (CC BY 4.0)**](https://creativecommons.org/licenses/by/4.0) license. Please refer to the [documentation](https://dev.meteostat.net/license) for more information.
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[downloads-shield]: https://img.shields.io/pypi/dm/meteostat
+[downloads-url]: https://pypi.org/project/meteostat/
+[provider-tests-shield]: https://github.com/meteostat/meteostat/actions/workflows/provider-tests.yml/badge.svg
+[provider-tests-url]: https://github.com/meteostat/meteostat/actions/workflows/provider-tests.yml
+[issues-shield]: https://img.shields.io/github/issues/meteostat/meteostat.svg
+[issues-url]: https://github.com/meteostat/meteostat/issues
+[license-shield]: https://img.shields.io/github/license/meteostat/meteostat.svg
+[license-url]: https://github.com/meteostat/meteostat?tab=readme-ov-file#-license
+[product-screenshot]: https://dev.meteostat.net/assets/images/example-8b6cf2a3fe2efa285bc72d7dc72c4865.png
+[stars-shield]: https://img.shields.io/github/stars/meteostat/meteostat.svg
+[stars-url]: https://github.com/meteostat/meteostat/stargazers

meteostat-2.0.1/README.md

@@ -0,0 +1,113 @@
+<!-- PROJECT SHIELDS -->
+<div align="center">
+  
+  [![Downloads][downloads-shield]][downloads-url]
+  [![Provider Tests][provider-tests-shield]][provider-tests-url]
+  [![Issues][issues-shield]][issues-url]
+  [![MIT License][license-shield]][license-url]
+  [![Stargazers][stars-shield]][stars-url]
+  
+</div>
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/meteostat/meteostat">
+    <img src="https://media.meteostat.net/icon.svg" alt="Meteostat Logo" width="80" height="80">
+  </a>
+
+  <h3 align="center">Meteostat Python Package</h3>
+
+  <p align="center">
+    Access and analyze historical weather and climate data with Python.
+    <p>
+      <a href="https://dev.meteostat.net/python"><strong>Explore the docs »</strong></a>
+    </p>
+    <p>
+      <a href="https://meteostat.net">Visit Website</a>
+      &middot;
+      <a href="https://github.com/meteostat/meteostat/issues">Report Bug</a>
+      &middot;
+      <a href="https://github.com/orgs/meteostat/discussions">Request Feature</a>
+    </p>
+  </p>
+</div>
+
+## 📚 Installation
+
+The Meteostat Python package is available through [PyPI](https://pypi.org/project/meteostat/):
+
+```sh
+pip install meteostat
+```
+
+## 🚀 Usage
+
+Let's plot 2018 temperature data for Frankfurt, Germany:
+
+```python
+from datetime import date
+import matplotlib.pyplot as plt
+import meteostat as ms
+
+# Specify location and time range
+POINT = ms.Point(50.1155, 8.6842, 113)  # Try with your location
+START = date(2018, 1, 1)
+END = date(2018, 12, 31)
+
+# Get nearby weather stations
+stations = ms.stations.nearby(POINT, limit=4)
+
+# Get daily data & perform interpolation
+ts = ms.daily(stations, START, END)
+df = ms.interpolate(ts, POINT).fetch()
+
+# Plot line chart including average, minimum and maximum temperature
+df.plot(y=[ms.Parameter.TEMP, ms.Parameter.TMIN, ms.Parameter.TMAX])
+plt.show()
+```
+
+Take a look at the expected output:
+
+![2018 temperature data for Frankfurt, Germany][product-screenshot]
+
+## 🤝 Contributing
+
+Please read our [contributing guidelines](https://dev.meteostat.net/python/contributing) for details on how to contribute to the Meteostat Python library.
+
+**Top contributors**
+
+<a href="https://github.com/meteostat/meteostat/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=meteostat/meteostat" alt="Meteostat Contributors" />
+</a>
+
+## 🌟 Featured In
+
+Meteostat has been featured and used by various media outlets and organizations, including:
+
+- [Towards Data Science](https://towardsdatascience.com/get-temperature-data-by-location-with-python-52ed872dd621/)
+- [ZEIT ONLINE](https://www.zeit.de/digital/internet/2022-03/desinformation-russland-ukraine-fotos-fake-news-falschinformation-echtheit)
+- [Deutsche Presse-Agentur (dpa)](https://dpa-factchecking.com/germany/230103-99-92282/)
+- [heise online](https://www.heise.de/news/Open-Source-Projekt-zu-Klimadaten-Meteostat-Python-Library-1-0-erschienen-4985015.html)
+
+Join the growing community of users and researchers relying on Meteostat for their weather data needs.
+
+## 📄 License
+
+Meteostat is licensed under the [**MIT License**](https://github.com/meteostat/meteostat/blob/main/LICENSE). Data provided by Meteostat is generally licensed under the [**Creative Commons Attribution 4.0 International (CC BY 4.0)**](https://creativecommons.org/licenses/by/4.0) license. Please refer to the [documentation](https://dev.meteostat.net/license) for more information.
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[downloads-shield]: https://img.shields.io/pypi/dm/meteostat
+[downloads-url]: https://pypi.org/project/meteostat/
+[provider-tests-shield]: https://github.com/meteostat/meteostat/actions/workflows/provider-tests.yml/badge.svg
+[provider-tests-url]: https://github.com/meteostat/meteostat/actions/workflows/provider-tests.yml
+[issues-shield]: https://img.shields.io/github/issues/meteostat/meteostat.svg
+[issues-url]: https://github.com/meteostat/meteostat/issues
+[license-shield]: https://img.shields.io/github/license/meteostat/meteostat.svg
+[license-url]: https://github.com/meteostat/meteostat?tab=readme-ov-file#-license
+[product-screenshot]: https://dev.meteostat.net/assets/images/example-8b6cf2a3fe2efa285bc72d7dc72c4865.png
+[stars-shield]: https://img.shields.io/github/stars/meteostat/meteostat.svg
+[stars-url]: https://github.com/meteostat/meteostat/stargazers

meteostat-2.0.1/meteostat/__init__.py

@@ -0,0 +1,54 @@
+"""
+█▀▄▀█ █▀▀ ▀█▀ █▀▀ █▀█ █▀ ▀█▀ ▄▀█ ▀█▀
+█░▀░█ ██▄ ░█░ ██▄ █▄█ ▄█ ░█░ █▀█ ░█░
+
+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 4.0 International
+License.
+
+The code is licensed under the MIT license.
+"""
+
+__appname__ = "meteostat"
+__version__ = "2.0.1"
+
+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__ = [
+    "config",
+    "daily",
+    "hourly",
+    "Granularity",
+    "interpolate",
+    "Inventory",
+    "lapse_rate",
+    "License",
+    "merge",
+    "monthly",
+    "normals",
+    "Parameter",
+    "Point",
+    "Provider",
+    "purge",
+    "Station",
+    "stations",
+    "TimeSeries",
+    "UnitSystem",
+]

meteostat-2.0.1/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-2.0.1/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-2.0.1/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)