v1.5

.github/workflows/ci.yml

@@ -51,23 +51,42 @@
 
     - name: Test with pytest
       run: |
-        python -m pytest tests/ -v --tb=short
-      continue-on-error: true  # Allow tests to fail until test suite is implemented
+        python -m pytest tests/ -v --tb=short --cov=vayuayan --cov-report=term-missing --cov-report=xml
 
     - name: Test CLI functionality
       run: |
         python -m vayuayan --help
         python -c "import vayuayan; print('Package imports successfully')"
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install docs dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[docs]"
+
+    - name: Build docs (fail on broken build)
+      env:
+        SPHINX_BUILD: "true"
+      run: sphinx-build -b html docs docs/_build/html
+
   security:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
 
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
 
     - name: Install bandit
       run: |

.github/workflows/docs-hostinger.yml

@@ -0,0 +1,46 @@
+name: docs-hostinger
+
+on:
+  push:
+    branches: [main, master]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: docs-hostinger-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      - name: Build Sphinx site
+        env:
+          SPHINX_BUILD: "true"
+        run: sphinx-build -b html docs docs/_build/html
+
+      - name: Deploy to Hostinger
+        uses: burnett01/rsync-deployments@7.0.1
+        with:
+          switches: -avzr --delete
+          path: docs/_build/html/
+          remote_path: /var/www/r-pkgdown/${{ github.event.repository.name }}/docs/
+          remote_host: ${{ secrets.HOSTINGER_HOST }}
+          remote_port: ${{ secrets.HOSTINGER_PORT }}
+          remote_user: ${{ secrets.HOSTINGER_USER }}
+          remote_key: ${{ secrets.HOSTINGER_SSH_KEY }}

.github/workflows/gh-pages.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install -e ".[docs]"
 
       - name: Build docs
         run: |

.github/workflows/publish.yml

@@ -76,7 +76,7 @@ jobs:
         name: python-package-distributions
         path: dist/
     - name: Sign the dists with Sigstore
-      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
       with:
         inputs: >-
           ./dist/*.tar.gz

docs/conf.py

@@ -97,6 +97,7 @@
 html_theme = "furo"
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
+html_baseurl = "https://vayuayan.saketlab.org/"
 
 # Logo configuration
 html_logo = "assets/vayuayan.png"

docs/history.rst

@@ -3,6 +3,12 @@ History
 
 Release history and changelog for vayuayan.
 
+v0.1.5 (2026-06-27)
+------------------
+
+* Added Google Earth Engine fallback for PM2.5 data when AWS S3 returns 403, with automatic GEE project detection and ``setup_earth_engine()`` helper
+* Added support for V5 (V5.GL.05.02, GWR-based) WUSTL ACAG data alongside the default V6
+
 v0.1.4 (2025-11-30)
 ------------------
 

pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=45", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "vayuayan"
-version = "0.1.4"
+dynamic = ["version"]
 description = "Package for fetching and analyzing air quality data from multiple sources"
 readme = "README.md"
 license = "MIT"
@@ -41,7 +41,9 @@ dependencies = [
     "rioxarray>=0.15.0",
     "xarray>=2024.7.0",
     "netCDF4>=1.7.2",
-    "tqdm>=4.62.0"
+    "tqdm>=4.62.0",
+    "earthengine-api>=0.1.384",
+    "boto3>=1.26.0"
 ]
 
 [project.optional-dependencies]
@@ -68,7 +70,7 @@ notebooks = [
 [project.urls]
 Homepage = "https://github.com/saketlab/vayuayan"
 Repository = "https://github.com/saketlab/vayuayan.git"
-Documentation = "https://saketlab.github.io/vayuayan"
+Documentation = "https://vayuayan.saketlab.org"
 "Bug Tracker" = "https://github.com/saketlab/vayuayan/issues"
 
 [project.scripts]
@@ -77,6 +79,9 @@ vayuayan = "vayuayan.cli:main"
 [tool.setuptools]
 packages = ["vayuayan"]
 
+[tool.setuptools.dynamic]
+version = {attr = "vayuayan.__version__"}
+
 [tool.setuptools.package-data]
 vayuayan = ["py.typed"]
 

tests/test_constants.py

@@ -0,0 +1,32 @@
+"""Tests for config-path helpers and AQI threshold table."""
+
+from pathlib import Path
+
+from vayuayan.constants import (
+    AQI_CATEGORIES,
+    get_config_dir,
+    get_gee_project_file,
+)
+
+
+def test_get_config_dir(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    monkeypatch.setattr("platform.system", lambda: "Linux")
+    d = get_config_dir()
+    assert d == tmp_path / "vayuayan"
+    assert d.is_dir()  # created on call
+
+
+def test_get_gee_project_file(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    monkeypatch.setattr("platform.system", lambda: "Linux")
+    f = get_gee_project_file()
+    assert f == tmp_path / "vayuayan" / "gee_project"
+    assert isinstance(f, Path)
+
+
+def test_aqi_categories_contiguous():
+    # Bands must be ordered and non-overlapping.
+    bands = list(AQI_CATEGORIES.values())
+    for lo, hi in zip(bands, bands[1:]):
+        assert lo["max"] + 1 == hi["min"]

tests/test_exceptions.py

@@ -0,0 +1,26 @@
+"""All custom exceptions must derive from CPCBError."""
+
+import pytest
+
+from vayuayan import exceptions as exc
+
+
+@pytest.mark.parametrize(
+    "cls",
+    [
+        exc.NetworkError,
+        exc.DataParsingError,
+        exc.DataProcessingError,
+        exc.CityNotFoundError,
+        exc.StationNotFoundError,
+        exc.InvalidDataError,
+        exc.AuthenticationError,
+        exc.RateLimitError,
+        exc.ConfigurationError,
+        exc.FileNotFoundError,
+    ],
+)
+def test_inherits_base(cls):
+    assert issubclass(cls, exc.CPCBError)
+    with pytest.raises(exc.CPCBError):
+        raise cls("boom")

tests/test_utils.py

@@ -0,0 +1,83 @@
+"""Tests for pure utility functions (no network/IO)."""
+
+import numpy as np
+import pytest
+
+from vayuayan.utils import (
+    clean_station_name,
+    get_aqi_category,
+    haversine_distance,
+    sort_station_data,
+)
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("Dr. Karni Singh Shooting Range, Delhi - DPCC",
+         "Dr_Karni_Singh_Shooting_Range_Delhi_DPCC"),
+        ("ITO, Delhi - DPCC", "ITO_Delhi_DPCC"),
+        ("  spaced   out  ", "spaced_out"),
+        ("", ""),
+        ("!!!", ""),
+    ],
+)
+def test_clean_station_name(raw, expected):
+    assert clean_station_name(raw) == expected
+
+
+def test_clean_station_name_non_string():
+    assert clean_station_name(None) == ""  # type: ignore[arg-type]
+
+
+@pytest.mark.parametrize(
+    "value,category",
+    [
+        (0, "Good"),
+        (50, "Good"),
+        (51, "Satisfactory"),
+        (100, "Satisfactory"),
+        (200, "Moderate"),
+        (300, "Poor"),
+        (400, "Very Poor"),
+        (401, "Severe"),
+        (9999, "Severe"),
+    ],
+)
+def test_get_aqi_category(value, category):
+    assert get_aqi_category(value) == category
+
+
+def test_get_aqi_category_nan():
+    assert get_aqi_category(np.nan) == "No Data"
+
+
+def test_haversine_zero_distance():
+    assert haversine_distance(19.07, 72.87, 19.07, 72.87) == pytest.approx(0.0)
+
+
+def test_haversine_known_distance():
+    # Mumbai -> Delhi is ~1150 km; allow generous tolerance.
+    d = haversine_distance(19.0760, 72.8777, 28.7041, 77.1025)
+    assert 1100 < d < 1200
+
+
+def test_haversine_symmetric():
+    a = haversine_distance(0, 0, 10, 10)
+    b = haversine_distance(10, 10, 0, 0)
+    assert a == pytest.approx(b)
+
+
+def test_sort_station_data_live_first():
+    data = [
+        {
+            "cityName": "Delhi",
+            "stationsInCity": [
+                {"name": "B", "live": False},
+                {"name": "A", "live": True},
+            ],
+        }
+    ]
+    result = sort_station_data(data)
+    names = [s["name"] for s in result[0]["stationsInCity"]]
+    assert names == ["A", "B"]  # live station first

vayuayan/__init__.py

@@ -18,7 +18,7 @@
     >>> location = live.get_system_location()
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.5"
 __author__ = "Saket Choudhary"
 __email__ = "saketc@iitb.ac.in"
 __description__ = (
@@ -28,9 +28,12 @@
 __url__ = "https://github.com/saketlab/vayuayan"
 
 # Import main client classes
-from .air_quality_client import CPCBHistorical, CPCBLive, PM25Client
+from .air_quality_client import CPCBHistorical, CPCBLive, PM25Client, setup_earth_engine
 from .client import CPCBClient
 
+# Import configuration helpers
+from .constants import get_config_dir, get_gee_project_file
+
 # Import exceptions for convenience
 from .exceptions import (
     AuthenticationError,
@@ -62,6 +65,10 @@
     "CPCBHistorical",
     "CPCBLive",
     "PM25Client",
+    # Setup helpers
+    "setup_earth_engine",
+    "get_config_dir",
+    "get_gee_project_file",
     # Exceptions
     "CPCBError",
     "NetworkError",