Python client: climate_api.open() convenience function for dataset access

[turban]

Background

Inspired by dynamical.org, which exposes climate data through a minimal Python interface:

ds = dynamical_catalog.open("noaa-gefs-forecast-35-day")

The Climate API already supports this pattern — the STAC catalog exposes all the metadata needed to open any published dataset with xarray. The current user guide walks through the discovery steps manually.

Proposed interface

from climate_api.client import open_dataset, list_datasets

ds = open_dataset("chirps3_precipitation_daily_rwa",
                  base_url="http://localhost:8000")

Under the hood this would:

1. GET /stac/collections/{dataset_id}
2. Read assets["zarr"]["href"] and xarray:open_kwargs
3. Return xr.open_zarr(href, **open_kwargs)

A list_datasets(base_url=...) companion would return available dataset IDs from the catalog.

Location

Rather than a separate PyPI package, the client interface fits naturally in this repository as src/climate_api/client.py. The open_dataset function in examples/stac_discover_and_open.py is already a working prototype of the core logic.

A standalone package would only make sense if users needed a minimal install without the full server stack. For typical DHIS2 deployments server and client are used together, so that separation adds versioning overhead without real benefit.

Once the core API is pip-installable (see #61), importing climate_api.client from an external project becomes straightforward without any additional packaging.

Implementation notes

• No new server endpoints required — everything is already exposed via STAC
• The prototype logic is in examples/stac_discover_and_open.py
• Should use httpx (already a declared dependency) for HTTP requests