gardenpy-meteocat

Reference evapotranspiration (ETo) calculations from Meteocat station data for the Meteocat Home Assistant integration.

gardenpy-meteocat is a Python library that computes the reference evapotranspiration (ETo) locally from the weather data already fetched by the Meteocat Home Assistant integration, following the FAO-56 methodology. This avoids calling the Meteocat XEMA API for the ETo variable (6006), saving quota.

Features

• FAO-56 Penman-Monteith (daily and hourly), the reference standard.
• Nighttime ETo included: the hourly equation computes evapotranspiration during the night when wind is present and humidity is low, matching the behaviour of Meteocat's official ETo since July 2026.
• Hargreaves-Samani fallback when humidity, wind or radiation data are missing.
• Solar radiation estimated from temperature range when no radiometer is available.
• Consumes the same station JSON returned by MeteocatStationData.get_station_data (no extra API calls).
• Returns hourly values in the same format as the Meteocat variable 6006 (baseHoraria HO), so it can be used as a drop-in replacement.

Installation

pip install gardenpy-meteocat

Quick start

from gardenpy import Evapotranspiration

eto = Evapotranspiration(latitude=41.38197, longitude=1.93564, elevation=252)

# station_data is the JSON returned by MeteocatStationData.get_station_data
daily = eto.daily(station_data)      # -> {"date", "method", "eto_mm", "inputs"}
hourly = eto.hourly(station_data)    # -> {"date", "method", "eto_daily_mm", "codi": 6006, "lectures": [...]}

The hourly() result matches the structure of the Meteocat API variable 6006, allowing it to replace the API call without consuming XEMA quota.

Methods

• penman_monteith_daily(tmax, tmin, rh_max, rh_min, u2, rs, latitude, jday, elevation)
• penman_monteith_hourly(t, rh, u2, rs, latitude, jday, hour, longitude, elevation)
• hargreaves_samani(tmax, tmin, latitude, jday)
• estimated_solar_radiation(tmax, tmin, latitude, jday)

All equations follow the FAO-56 documentation (Chapters 3 and 4).

Tests

pip install -e .[test]
pytest

Release

El repositorio incluye un workflow de GitHub Actions (.github/workflows/release.yml) basado en python-semantic-release. Cada push a la rama master ejecuta los tests y, si los commits siguen el formato conventional commits, calcula la versión siguiente, actualiza pyproject.toml y gardenpy/version.py, genera el changelog, crea la tag vX.Y.Z, crea el release de GitHub y publica el paquete en PyPI — todo automáticamente.

Para publicar una versión nueva no hay que tocar nada a mano; basta con usar mensajes de commit convencionales:

• feat: ... → incremento de versión menor (1.1.0)
• fix: ... → incremento de parche (1.0.1)
• feat!: ... o BREAKING CHANGE: → incremento de versión mayor (2.0.0)
• otros tipos (docs:, chore:, refactor:, ...) → no generan release

La primera vez, si el repositorio no tiene ninguna tag, es recomendable empujar una tag base v1.0.0 para que PSR tome como referencia el estado actual antes del flujo automático (aunque no dispara el workflow, que solo reacciona a push a master).

Requisitos previos:

• Añade en GitHub el secret PYPI_API_TOKEN con un token de PyPI (scope al proyecto gardenpy-meteocat o a toda la cuenta) que se crea en https://pypi.org/manage/account/token/.
• pytest se ejecuta en CI; los ficheros de validación en tests/files/ deben estar incluidos en el repositorio para que el test contra los datos oficiales se ejecute (si no están, ese test se omite).

License

Apache-2.0