atmofetch 0.1.0__tar.gz

atmofetch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: Ruff check
+        run: ruff check src/ tests/
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Mypy
+        run: mypy src/atmofetch --ignore-missing-imports
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v

atmofetch-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.venv/

atmofetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AtmoFetch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

atmofetch-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: atmofetch
+Version: 0.1.0
+Summary: Download meteorological data from publicly available repositories
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: lxml>=5.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# atmofetch
+
+Python package to download *in-situ* meteorological data from publicly available repositories:
+
+- **OGIMET** ([ogimet.com](http://ogimet.com/index.phtml.en)) — up-to-date SYNOP dataset (hourly & daily)
+- **University of Wyoming** ([weather.uwyo.edu](http://weather.uwyo.edu/upperair/)) — atmospheric vertical profiling (sounding) data
+- **NOAA NCEI** ([ncei.noaa.gov](https://www.ncei.noaa.gov/pub/data/noaa/)) — Integrated Surface Hourly (ISH) meteorological data
+- **NOAA GML** ([gml.noaa.gov](https://gml.noaa.gov/ccgg/trends/)) — Mauna Loa CO2 monthly measurements
+
+## Installation
+
+```bash
+pip install atmofetch
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Download hourly NOAA ISH data
+
+```python
+from atmofetch import meteo_noaa_hourly
+
+df = meteo_noaa_hourly(station="037720-99999", year=2023)
+print(df.head())
+```
+
+### Download daily OGIMET data
+
+```python
+from atmofetch import meteo_ogimet
+
+df = meteo_ogimet(interval="daily", station=72503, coords=True)
+print(df.head())
+```
+
+### Download CO2 data from Mauna Loa
+
+```python
+from atmofetch import meteo_noaa_co2
+
+co2 = meteo_noaa_co2()
+print(co2.tail())
+```
+
+### Download atmospheric sounding
+
+```python
+from atmofetch import sounding_wyoming
+
+profile, metadata = sounding_wyoming(wmo_id=45004, yy=2023, mm=7, dd=17, hh=12)
+print(profile.head())
+```
+
+### Find nearest stations
+
+```python
+from atmofetch import nearest_stations_noaa, nearest_stations_ogimet
+
+# NOAA stations near London
+noaa = nearest_stations_noaa(country="UNITED KINGDOM", point=(-0.1, 51.5))
+print(noaa[["STATION NAME", "distance"]].head())
+
+# OGIMET stations near Paris
+ogimet = nearest_stations_ogimet(country="France", point=(2.35, 48.86))
+print(ogimet.head())
+```
+
+### Calculate distance between two points
+
+```python
+from atmofetch import spheroid_dist
+
+km = spheroid_dist((18.63, 54.37), (17.02, 54.47))
+print(f"Distance: {km:.1f} km")
+```
+
+## API Reference
+
+### Meteorological Data
+
+| Function | Source | Description |
+|---|---|---|
+| `meteo_ogimet()` | OGIMET | Hourly or daily SYNOP data |
+| `ogimet_hourly()` | OGIMET | Hourly SYNOP data |
+| `ogimet_daily()` | OGIMET | Daily SYNOP summaries |
+| `meteo_noaa_hourly()` | NOAA ISH | Hourly data (some stations >100 years) |
+| `meteo_noaa_co2()` | NOAA GML | Monthly CO2 from Mauna Loa |
+| `sounding_wyoming()` | U. Wyoming | Vertical atmospheric profiles (TEMP/BUFR) |
+
+### Station Discovery
+
+| Function | Source | Description |
+|---|---|---|
+| `stations_ogimet()` | OGIMET | List all stations for a country |
+| `nearest_stations_ogimet()` | OGIMET | Find nearest OGIMET stations |
+| `nearest_stations_noaa()` | NOAA | Find nearest NOAA ISH stations |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `spheroid_dist()` | Distance (km) between two (lon, lat) points |
+
+## License
+
+MIT

atmofetch-0.1.0/README.md

@@ -0,0 +1,112 @@
+# atmofetch
+
+Python package to download *in-situ* meteorological data from publicly available repositories:
+
+- **OGIMET** ([ogimet.com](http://ogimet.com/index.phtml.en)) — up-to-date SYNOP dataset (hourly & daily)
+- **University of Wyoming** ([weather.uwyo.edu](http://weather.uwyo.edu/upperair/)) — atmospheric vertical profiling (sounding) data
+- **NOAA NCEI** ([ncei.noaa.gov](https://www.ncei.noaa.gov/pub/data/noaa/)) — Integrated Surface Hourly (ISH) meteorological data
+- **NOAA GML** ([gml.noaa.gov](https://gml.noaa.gov/ccgg/trends/)) — Mauna Loa CO2 monthly measurements
+
+## Installation
+
+```bash
+pip install atmofetch
+```
+
+Or install from source:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Download hourly NOAA ISH data
+
+```python
+from atmofetch import meteo_noaa_hourly
+
+df = meteo_noaa_hourly(station="037720-99999", year=2023)
+print(df.head())
+```
+
+### Download daily OGIMET data
+
+```python
+from atmofetch import meteo_ogimet
+
+df = meteo_ogimet(interval="daily", station=72503, coords=True)
+print(df.head())
+```
+
+### Download CO2 data from Mauna Loa
+
+```python
+from atmofetch import meteo_noaa_co2
+
+co2 = meteo_noaa_co2()
+print(co2.tail())
+```
+
+### Download atmospheric sounding
+
+```python
+from atmofetch import sounding_wyoming
+
+profile, metadata = sounding_wyoming(wmo_id=45004, yy=2023, mm=7, dd=17, hh=12)
+print(profile.head())
+```
+
+### Find nearest stations
+
+```python
+from atmofetch import nearest_stations_noaa, nearest_stations_ogimet
+
+# NOAA stations near London
+noaa = nearest_stations_noaa(country="UNITED KINGDOM", point=(-0.1, 51.5))
+print(noaa[["STATION NAME", "distance"]].head())
+
+# OGIMET stations near Paris
+ogimet = nearest_stations_ogimet(country="France", point=(2.35, 48.86))
+print(ogimet.head())
+```
+
+### Calculate distance between two points
+
+```python
+from atmofetch import spheroid_dist
+
+km = spheroid_dist((18.63, 54.37), (17.02, 54.47))
+print(f"Distance: {km:.1f} km")
+```
+
+## API Reference
+
+### Meteorological Data
+
+| Function | Source | Description |
+|---|---|---|
+| `meteo_ogimet()` | OGIMET | Hourly or daily SYNOP data |
+| `ogimet_hourly()` | OGIMET | Hourly SYNOP data |
+| `ogimet_daily()` | OGIMET | Daily SYNOP summaries |
+| `meteo_noaa_hourly()` | NOAA ISH | Hourly data (some stations >100 years) |
+| `meteo_noaa_co2()` | NOAA GML | Monthly CO2 from Mauna Loa |
+| `sounding_wyoming()` | U. Wyoming | Vertical atmospheric profiles (TEMP/BUFR) |
+
+### Station Discovery
+
+| Function | Source | Description |
+|---|---|---|
+| `stations_ogimet()` | OGIMET | List all stations for a country |
+| `nearest_stations_ogimet()` | OGIMET | Find nearest OGIMET stations |
+| `nearest_stations_noaa()` | NOAA | Find nearest NOAA ISH stations |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `spheroid_dist()` | Distance (km) between two (lon, lat) points |
+
+## License
+
+MIT

atmofetch-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "atmofetch"
+version = "0.1.0"
+description = "Download meteorological data from publicly available repositories"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pandas>=2.0",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+    "tqdm>=4.60",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.30",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atmofetch"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

atmofetch-0.1.0/src/atmofetch/__init__.py

@@ -0,0 +1,37 @@
+"""AtmoFetch - Download meteorological data from publicly available repositories.
+
+Data sources:
+- OGIMET (ogimet.com) — SYNOP station data (hourly & daily)
+- University of Wyoming — atmospheric vertical profiling (sounding) data
+- NOAA — Integrated Surface Hourly (ISH) and Mauna Loa CO2 data
+"""
+
+from atmofetch.noaa import meteo_noaa_hourly, meteo_noaa_co2, nearest_stations_noaa
+from atmofetch.ogimet import (
+    meteo_ogimet,
+    ogimet_daily,
+    ogimet_hourly,
+    stations_ogimet,
+    nearest_stations_ogimet,
+)
+from atmofetch.wyoming import sounding_wyoming
+from atmofetch._utils.distance import spheroid_dist
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # NOAA
+    "meteo_noaa_hourly",
+    "meteo_noaa_co2",
+    "nearest_stations_noaa",
+    # OGIMET
+    "meteo_ogimet",
+    "ogimet_daily",
+    "ogimet_hourly",
+    "stations_ogimet",
+    "nearest_stations_ogimet",
+    # Wyoming
+    "sounding_wyoming",
+    # Utilities
+    "spheroid_dist",
+]

atmofetch-0.1.0/src/atmofetch/_utils/__init__.py

@@ -0,0 +1,11 @@
+from atmofetch._utils.distance import spheroid_dist
+from atmofetch._utils.network import download, check_internet
+from atmofetch._utils.coordinates import get_coord_from_string, precip_split
+
+__all__ = [
+    "spheroid_dist",
+    "download",
+    "check_internet",
+    "get_coord_from_string",
+    "precip_split",
+]

atmofetch-0.1.0/src/atmofetch/_utils/coordinates.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import re
+
+import numpy as np
+import pandas as pd
+
+
+def get_coord_from_string(txt: str, pattern: str = "Longitude") -> float | None:
+    """Extract a decimal-degree coordinate from an Ogimet metadata string.
+
+    Parameters
+    ----------
+    txt : raw metadata string (e.g. ``"Latitude: 52-25N  Longitude: 016-50E ..."``)
+    pattern : ``"Longitude"`` or ``"Latitude"``
+    """
+    m = re.search(rf"{pattern}:\s*([\d]+)-([\d]+)(?:-([\d]+))?\s*([NSEW])", txt)
+    if m is None:
+        return None
+    deg, minutes, seconds, hemisphere = m.groups()
+    seconds = seconds or "0"
+    value = int(deg) + (int(minutes) * 5 / 3) / 100 + (int(seconds) * 5 / 3) / 100 / 60
+    if hemisphere in ("W", "S"):
+        value *= -1
+    return value
+
+
+def precip_split(precip: pd.Series, pattern: str = "/12") -> pd.Series:
+    """Split Ogimet precipitation string into numeric values for a given hour window.
+
+    Parameters
+    ----------
+    precip : Series of strings like ``"1.2/6h0.0/12h3.4/24h"``
+    pattern : ``"/6"``, ``"/12"``, or ``"/24"``
+    """
+
+    def _extract(val: str | None) -> float | None:
+        if val is None or (isinstance(val, float) and np.isnan(val)):
+            return None
+        parts = str(val).split("h")
+        for part in parts:
+            if pattern in part:
+                numeric = part.replace(pattern, "")
+                try:
+                    return float(numeric)
+                except ValueError:
+                    return None
+        return None
+
+    return precip.apply(_extract)

atmofetch-0.1.0/src/atmofetch/_utils/distance.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import math
+
+
+def spheroid_dist(p1: tuple[float, float], p2: tuple[float, float]) -> float:
+    """Distance between two points on a spheroid using Vincenty's formula.
+
+    Parameters
+    ----------
+    p1 : (lon, lat) in decimal degrees
+    p2 : (lon, lat) in decimal degrees
+
+    Returns
+    -------
+    Distance in kilometres.
+    """
+    r = 6_371_009  # mean earth radius in metres
+    lon1, lat1, lon2, lat2 = (v * math.pi / 180 for v in (*p1, *p2))
+    diff_long = lon2 - lon1
+
+    num = (math.cos(lat2) * math.sin(diff_long)) ** 2 + (
+        math.cos(lat1) * math.sin(lat2) - math.sin(lat1) * math.cos(lat2) * math.cos(diff_long)
+    ) ** 2
+    denom = math.sin(lat1) * math.sin(lat2) + math.cos(lat1) * math.cos(lat2) * math.cos(diff_long)
+    d = math.atan2(math.sqrt(num), denom)
+    return d * r / 1000

atmofetch-0.1.0/src/atmofetch/_utils/network.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_TIMEOUT = 30.0
+
+_OGIMET_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:143.0) Gecko/20100101 Firefox/143.0"
+    ),
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "pl,en-US;q=0.7,en;q=0.3",
+    "Referer": "https://ogimet.com/resynops.phtml.en",
+    "Cookie": "cookieconsent_status=dismiss; ogimet_serverid=huracan|aNaPt|aNaPj",
+}
+
+
+def check_internet() -> bool:
+    try:
+        httpx.head("https://www.google.com", timeout=5)
+        return True
+    except httpx.HTTPError:
+        return False
+
+
+def download(url: str, dest: Path | str | None = None, *, timeout: float = _TIMEOUT) -> bytes:
+    logger.info("Downloading %s", url)
+    resp = httpx.get(url, timeout=timeout, follow_redirects=True)
+    resp.raise_for_status()
+    if dest is not None:
+        Path(dest).write_bytes(resp.content)
+    return resp.content
+
+
+def fetch_text(
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    timeout: float = _TIMEOUT,
+) -> str:
+    logger.info("Fetching %s", url)
+    resp = httpx.get(url, headers=headers, timeout=timeout, follow_redirects=True)
+    resp.raise_for_status()
+    return resp.text
+
+
+def fetch_ogimet(url: str, *, timeout: float = _TIMEOUT) -> str:
+    return fetch_text(url, headers=_OGIMET_HEADERS, timeout=timeout)

atmofetch-0.1.0/src/atmofetch/noaa/__init__.py

@@ -0,0 +1,5 @@
+from atmofetch.noaa.hourly import meteo_noaa_hourly
+from atmofetch.noaa.co2 import meteo_noaa_co2
+from atmofetch.noaa.stations import nearest_stations_noaa
+
+__all__ = ["meteo_noaa_hourly", "meteo_noaa_co2", "nearest_stations_noaa"]

atmofetch-0.1.0/src/atmofetch/noaa/co2.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import io
+import logging
+
+import pandas as pd
+
+from atmofetch._utils.network import fetch_text
+
+logger = logging.getLogger(__name__)
+
+_CO2_URL = "https://gml.noaa.gov/webdata/ccgg/trends/co2/co2_mm_mlo.txt"
+
+
+def meteo_noaa_co2() -> pd.DataFrame:
+    """Download monthly CO2 measurements from Mauna Loa Observatory (NOAA).
+
+    Returns
+    -------
+    DataFrame with columns: yy, mm, yy_d, co2_avg, co2_interp, co2_seas, ndays, st_dev_days.
+    """
+    text = fetch_text(_CO2_URL)
+
+    lines = [line for line in text.splitlines() if not line.startswith("#")]
+    cleaned = "\n".join(lines)
+
+    df = pd.read_csv(
+        io.StringIO(cleaned),
+        sep=r"\s+",
+        header=None,
+        names=["yy", "mm", "yy_d", "co2_avg", "co2_interp", "co2_seas", "ndays", "st_dev_days"],
+        na_values=["-9.99", "-0.99"],
+    )
+    return df