Installation

Requirements

Coldcast targets Python 3.9+. Dependencies are declared in the project pyproject.toml (pandas, PyYAML, requests, cdsapi, ecmwf-opendata, netCDF4, xarray, …).

Install from a clone (editable)

From the repository root:

python -m pip install -e .

This installs the coldcast package from src/ and registers the coldcast console script.

Running the CLI on Windows

After pip install -e ., do not run:

python.exe coldcast

That form asks Python to open a local file named coldcast and will fail with can't open file ... when no such file exists.

Use the console script that pip registers for your environment (typical location: <Python root>\Scripts\coldcast.exe), for example:

coldcast --help
coldcast download noaa_hrrr --dry-run

If coldcast is not recognized, run it with a full path to coldcast.exe, or add your environment’s Scripts directory to PATH.

Alternatively, invoke the package module (works with the same interpreter you used for pip):

py -3.11 -m coldcast.cli --help
py -3.11 -m coldcast.cli download noaa_hrrr --dry-run

Using Poetry

poetry install

Run the CLI via:

poetry run coldcast download --help

Optional: documentation build dependencies

poetry install --with docs
sphinx-build -b html docs docs/_build/html

Then open docs/_build/html/index.html in a browser.

External credentials

Copernicus CDS (ERA5 / ERA5-LAND) Downloads use cdsapi. Configure a ~/.cdsapirc with your API URL and key as described in the CDS documentation.

ECMWF open data and reanalysis (ECMWF) Retrieval uses the ecmwf-opendata client. Public open-data endpoints generally do not need a personal token; follow ECMWF’s current guidance if that changes.

ECCC radar (optional HTTP auth) If your ECCC_RADAR settings include username / password, those are passed as HTTP basic auth to the configured URLs.

NOAA SNODAS URLs are built from the collaborator product layout documented by NOAA; no Coldcast-specific API key is required.

Alberta WISKI (ALBERTA_API) The default upstream endpoint is public (no API key). Configure a mapping CSV with Station, Parameter, and TsID columns in your ALBERTA_API.mapping_csv setting (or override with --stations-csv).