Metadata-Version: 2.4
Name: weather-cli-era5
Version: 2026.1.20
Summary: CLI to download a 10-years weather data from ERA5 and process it in reports
Author-email: David Issa Mattos <issamattos.david@gmail.com>
License: MIT License
        
        Copyright (c) 2026
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cdsapi
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: fire
Requires-Dist: geopy
Dynamic: license-file

# sharve-era5-request
CLI for downloading ERA5 single-level data and generating reports.

## Install

Install with pip

```
pip install weather-cli-era5
```

Local installation from the repository

```
pip install .
```

Or for local installation in editable mode (for development):

```
pip install -e .
```

## Register for the ERA5 to get an API token

1. If you do not have an account yet, please register https://cds.climate.copernicus.eu/
2. If you are not logged in, please login 
3. Open your profile and copy API key


## Configure (one time only)

weather configure --token paste_your_api_key_token

Additional config (if needed)
```bash
# Configure token (CDS or ADS)
weather configure --token <UID:APIKEY> [--url https://ads.atmosphere.copernicus.eu/api]
```

## Usage

Workflow overview:

- `weather download`: fetch 2016-2025 ERA5-Land point time-series (fixed variable set) for one location, with optional automatic geocoding.
- `weather save`: write the processed time-series for a location (from cache) to CSV.
- `weather report`: generate an HTML report for one location or an aggregated report across multiple locations.
- `weather list`: list cached locations (names/country/coords from the database).
- `weather refresh-database`: rebuild the SQLite cache from all downloaded datasets.

### Commands

**Download fixed variables for a point (2016-2025)**

```
weather download --name Gothenburg --lat 57.7 --lon 11.9
```

Notes: downloads ERA5-Land time-series for the fixed variables into `.weather_era5/gothenburg.zip` (zip archive containing CSV files). If the file exists, download is skipped.

**Download with automatic geocoding**

```
weather download --name Gothenburg --find-city Gothenburg --find-country Sweden
```

This uses Nominatim to resolve latitude/longitude and country code; you can also provide `--find-city` alone and let reverse geocoding pick the country.

**Save point data to CSV**

```
weather save --name Gothenburg --output ./gothenburg.csv
```

This reads the downloaded point dataset for the location and writes a CSV with all variables aligned on time.

**Generate a report**

```
weather report --name Gothenburg
```

Produces an HTML report with one summary table for all variables and per-variable histogram and climatology line plots.

**Generate an aggregated report across cities (weighted)**

```
weather report --name "Gothenburg,Oslo" --weights "2,1"
```

Loads each city from the cache, aggregates metrics with provided weights (defaults to equal weights), and writes a combined HTML report.

**List cached locations**

```
weather list
```

Shows name (from the database, falling back to filename if missing), country, and coordinates for cached datasets.

**Refresh the cache database**

```
weather refresh-database
```

Reprocesses all downloaded ZIP/CSV files into the SQLite cache (useful after schema changes or manual file edits).

### Options (common)

- `--name`: label used for the dataset filename (`<name>.zip`) and cache key
- `--lat`, `--lon`: latitude/longitude for downloads
- `--output`: optional output path for `save`; defaults to `.weather_era5/<name>.csv`

### Notes

- A download for a specific location takes approximately 30s
- Datasets are stored in `.weather_era5/` under your home directory by default; a SQLite cache (`weather.sqlite`) powers `report`, `save`, and `list`.
- `save` and `report` read only from the cache; run `download` (or `refresh-database` if you already have ZIP/CSV files) first.

