Metadata-Version: 2.4
Name: meteoswiss-precipitation
Version: 0.2.2
Summary: MeteoSwiss precipitation nowcast and rain-start prediction (extracted from ha-meteoswiss-rainstart)
Author: Carsten Senf
License-Expression: MIT
Project-URL: Homepage, https://github.com/csenf/meteoswiss-precipitation
Project-URL: Documentation, https://github.com/csenf/meteoswiss-precipitation#readme
Project-URL: Repository, https://github.com/csenf/meteoswiss-precipitation
Project-URL: Issues, https://github.com/csenf/meteoswiss-precipitation/issues
Project-URL: Changelog, https://github.com/csenf/meteoswiss-precipitation/releases
Keywords: meteoswiss,precipitation,nowcast,weather,switzerland,rain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: stac
Requires-Dist: numpy>=1.26; extra == "stac"
Requires-Dist: xarray>=2024.1; extra == "stac"
Requires-Dist: h5netcdf>=1.3; extra == "stac"
Requires-Dist: h5py>=3.10; extra == "stac"
Provides-Extra: local
Requires-Dist: numpy>=1.26; extra == "local"
Provides-Extra: all
Requires-Dist: numpy>=1.26; extra == "all"
Requires-Dist: xarray>=2024.1; extra == "all"
Requires-Dist: h5netcdf>=1.3; extra == "all"
Requires-Dist: h5py>=3.10; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: numpy>=1.26; extra == "dev"
Requires-Dist: xarray>=2024.1; extra == "dev"
Requires-Dist: h5netcdf>=1.3; extra == "dev"
Requires-Dist: h5py>=3.10; extra == "dev"
Dynamic: license-file

# meteoswiss-precipitation

Python library for **MeteoSwiss precipitation nowcast and rain-start prediction**,
extracted from [ha-meteoswiss-rainstart](https://github.com/csenf/ha-meteoswiss-rainstart)
so it can be used outside Home Assistant (embedded devices, scripts, other apps).

No Home Assistant imports anywhere. The core is `httpx` + stdlib only, so it
runs on a Raspberry Pi without compiling native wheels.

## What it does

Samples MeteoSwiss precipitation data at a WGS84 location and answers two
questions:

1. **When does rain start?** (scalar `minutes_until_rain` + `rain_start`)
2. **What does the precipitation timeline look like?** (per-frame `samples`,
   used to draw intensity bars)

Three data sources, tried in order (mirrors the HA integration):

- `radar_nowcast` — the MeteoSwiss precipitation website JSON (RZC + INCA rate,
  5-minute frames). **Primary, httpx-only.**
- `nowcasting` — STAC RR-INCA NetCDF grid (10-minute). Needs the `stac` extra.
- `local_forecasting` — hourly point-forecast CSV fallback. Needs the `local` extra.

## Install

```sh
# core (radar nowcast only)
pip install meteoswiss-precipitation

# with all fallbacks
pip install "meteoswiss-precipitation[all]"
```

From source:

```sh
pip install "meteoswiss-precipitation @ git+https://github.com/csenf/meteoswiss-precipitation@v0.2.0"
```

## Usage

```python
from meteoswiss_precipitation import fetch_rain_start, fetch_radar_report

# scalar rain-start (tries radar -> stac -> local)
result = fetch_rain_start(46.8989, 7.4951, threshold=0.1)
print(result.minutes_until_rain, result.rain_start, result.intensity)

# full timeline for drawing bars (radar only, httpx only)
report = fetch_radar_report(46.8989, 7.4951, threshold=0.1)
for frame in report.samples:
    print(frame["time"], frame["kind"], frame["wet"], frame["rate_lo"], frame["label"])
```

The `samples` list is the source of truth for timeline bars; each frame has
`timestamp`, `time` (HH:MM), `kind` (`measurement` | `forecast`), `day`,
`wet`, `rate_lo` (mm/h), `label`, `color`, and (when dry) `nearest_km`.

## Layout

```
src/meteoswiss_precipitation/
    radar.py   # radar nowcast parser + pipeline (core, httpx-only)
    geo.py     # pure-Python WGS84 <-> LV95 + CH bounds
    scan.py    # numpy rain-start scan + forecast context
    stac.py    # STAC RR-INCA NetCDF grid (stac extra)
    local.py   # local point-forecast CSV (local extra)
    models.py  # dataclasses (RainStartResult, RadarReport, ...)
    errors.py  # exception hierarchy
```

## Provenance

Ported from `ha-meteoswiss-rainstart` `custom_components/...`
(`radar_nowcast.py`, `api.py`, `local_forecast.py`, `const.py`) plus tests.
LV95 conversion is pure Python (`geo.py`, ~2 m accuracy vs pyproj) so the core
has no compiled dependencies.

## Publishing

Releases and PyPI uploads are documented in [docs/publishing.md](docs/publishing.md).

## Disclaimer

Uses public MeteoSwiss / geo.admin.ch data and an **undocumented** website JSON
API for radar animation. Not affiliated with MeteoSwiss. Use at your own risk
for non-critical applications.
