| Name | weatheasy JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A service for easy weather data acquiring |
| upload_time | 2024-09-03 10:24:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# WeathEasy
A service for easy weather data acquiring. It uses [Zarr](https://zarr.readthedocs.io/en/stable/)
as data storage for fast time series queries.
## Installation
We highly recommend to use a virtual environment:
```sh
python3 -m venv /path/to/venv
. /path/to/venv/bin/activate
```
On Windows:
```powershell
python3 -m venv C:\path\to\venv
C:\path\to\venv\Scripts\activate
```
Install WeathEasy from pypi.org:
```sh
python3 -m pip install weatheasy
```
To install the latest (possibly unreleased) version from the GitHub repository:
```sh
python3 -m pip install git+https://github.com/AgroDT/WeathEasy.git
```
Check installation:
```sh
python3 -m weatheasy -v
```
## Extras
By default WeathEasy is only available from command line interface with local
storage. The following extras are available to extend its functionality:
- `s3` - enables support for S3-compatible storage for WeathEasy data
- `web` - enables web API endpoint
To install WeathEasy with extras run
```sh
python3 -m pip install weatheasy[s3,web]
```
## Configuration
WeathEasy web API service is configured with environment variables. Use
[.example.env](./.example.env) as reference. Also you can copy and edit this
file as `.env` or `.local.env`. WeathEasy will load it automatically.
```sh
cp .example.env .env
```
CLI applications are configured with command line arguments (see below).
## Launching
Before running WeathEasy you need to download weather and climate data. As of
late 2024 the CFSv2 reanalysis and actual forecast require a total about 65GiB
of space. CMIP6 requires about 390GiB of space.
It is also worth updating CFSv2 daily. Just run the download command on a
schedule. WeathEasy will download missing reanalysis data and update the
forecast if necessary. See [below](#download-cli) for details.
‼️ The initial download of data may take a long time: from several days to
several weeks, depending on network bandwidth, the state of the source data
servers, and (possibly) star positions.
### Download CLI
To download weather and climate data run:
```sh
python3 -m weatheasy.download -d STORE {cfs2,cmip6}
```
Where `STORE` can be a local path or an S3 link in format
`s3://<bucket>/<prefix>`.
For S3 you need to export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. For
any not-AWS S3 storages you also need to export `AWS_ENDPOINT_URL_S3`. See the
[Boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables)
for details.
Optionally you can provide a local path to `--download-dir` to preserve
original downloaded files (GRIB2 for CFSv2 and NetCDF for CMIP6).
A full example for CFSv2:
```sh
python3 -m weatheasy.download -d s3://weatheasy/zarr --download-dir ./downloads cfs2
```
To display the full help message, run:
```sh
python3 -m weatheasy.download -h
```
### Query CLI
To query downloaded data run:
```sh
python3 -m weatheasy -d STORE -o PATH {cfs2,cmip6} begin end latitude longitude var [var ...]
```
Where:
- `STORE` is the same as for downloading
- `PATH` is a path to write results to (by default, results are output to
console)
- `begin`, `end` are the date range boundaries in ISO format (yyyy-mm-dd)
- `latitude`, `longitude` are target coordinates in EPSG:4326 coordinate
reference system (decimal degrees WGS84)
The command line must ends with a space separated list of target variables to
query. To print a full list of available variables run:
```sh
python3 -m weatheasy list-vars
```
A full example for CFSv2, Moscow:
```sh
python3 -m weatheasy -d s3://weatheasy/zarr cfs2 \
2024-01-01 2024-01-31 \
55.75222 37.61556 \
TMIN TMAX TMP
```
To display the full help message, run:
```sh
python3 -m weatheasy -h
python3 -m weatheasy cfs2 -h
python3 -m weatheasy cmip6 -h
```
### Web API
After [configuring](#configuration) launch the web application with:
```sh
uvicorn weatheasy.web:app
```
By default it would be listening for incoming requests at
http://127.0.0.1:8000.
Interactive API docs are available at
http://127.0.0.1:8000/docs.
Alternative API docs are available at
http://127.0.0.1:8000/redoc.
Read the [Uvicorn docs](https://www.uvicorn.org/deployment/)
for a full list of supported arguments and options.
### Docker
We provide [Docker images](https://github.com/AgroDT/WeathEasy/pkgs/container/weatheasy)
with all installed dependencies to run WeathEasy. Pull it with:
```sh
docker pull ghcr.io/agrodt/weatheasy
```
The default entry point is the web API. Redefine it to use WeathEasy CLI. For
example, to download CFSv2 data with docker run:
```sh
docker run --rm -it \
--entrypoint python \
ghcr.io/agrodt/weatheasy \
-m weatheasy.download \
-d s3://weatheasy/zarr \
cfs2
```
Find an example for Docker Compose at [examples/docker-compose](examples/docker-compose).
## Development
WeathEasy is written in Python and managed by [Rye](https://rye.astral.sh/).
After cloning this repository, initialize the development environment with:
```sh
rye sync --all-features
```
We also recommend to install and use pre-commit:
```sh
rye tools install pre-commit
pre-commit install
```
You can develop WeathEasy with locally running S3-compatible object storage
[MinIO](https://min.io/). Launch it with:
```sh
docker compose -f compose.dev.yml up -d
```
Also you need to export next variables (see [.example.env](./.example.env)):
```sh
export AWS_ENDPOINT_URL_S3=http://127.0.0.1:9000
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
```
Raw data
{
"_id": null,
"home_page": null,
"name": "weatheasy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Margarita Usacheva <usa4eva.m@mail.ru>, Petr Tsymbarovich <petr@tsymbarovich.ru>",
"download_url": "https://files.pythonhosted.org/packages/72/77/bd868a81ae5237973c4d4b5251238daddb9d0e199069eecb0b66bec67632/weatheasy-0.2.0.tar.gz",
"platform": null,
"description": "# WeathEasy\r\n\r\nA service for easy weather data acquiring. It uses [Zarr](https://zarr.readthedocs.io/en/stable/)\r\nas data storage for fast time series queries.\r\n\r\n## Installation\r\n\r\nWe highly recommend to use a virtual environment:\r\n\r\n```sh\r\npython3 -m venv /path/to/venv\r\n. /path/to/venv/bin/activate\r\n```\r\n\r\nOn Windows:\r\n\r\n```powershell\r\npython3 -m venv C:\\path\\to\\venv\r\nC:\\path\\to\\venv\\Scripts\\activate\r\n```\r\n\r\nInstall WeathEasy from pypi.org:\r\n\r\n```sh\r\npython3 -m pip install weatheasy\r\n```\r\n\r\nTo install the latest (possibly unreleased) version from the GitHub repository:\r\n\r\n```sh\r\npython3 -m pip install git+https://github.com/AgroDT/WeathEasy.git\r\n```\r\n\r\nCheck installation:\r\n\r\n```sh\r\npython3 -m weatheasy -v\r\n```\r\n\r\n## Extras\r\n\r\nBy default WeathEasy is only available from command line interface with local\r\nstorage. The following extras are available to extend its functionality:\r\n\r\n- `s3` - enables support for S3-compatible storage for WeathEasy data\r\n- `web` - enables web API endpoint\r\n\r\nTo install WeathEasy with extras run\r\n\r\n```sh\r\npython3 -m pip install weatheasy[s3,web]\r\n```\r\n\r\n## Configuration\r\n\r\nWeathEasy web API service is configured with environment variables. Use\r\n[.example.env](./.example.env) as reference. Also you can copy and edit this\r\nfile as `.env` or `.local.env`. WeathEasy will load it automatically.\r\n\r\n```sh\r\ncp .example.env .env\r\n```\r\n\r\nCLI applications are configured with command line arguments (see below).\r\n\r\n## Launching\r\n\r\nBefore running WeathEasy you need to download weather and climate data. As of\r\nlate 2024 the CFSv2 reanalysis and actual forecast require a total about 65GiB\r\nof space. CMIP6 requires about 390GiB of space.\r\n\r\nIt is also worth updating CFSv2 daily. Just run the download command on a\r\nschedule. WeathEasy will download missing reanalysis data and update the\r\nforecast if necessary. See [below](#download-cli) for details.\r\n\r\n\u203c\ufe0f The initial download of data may take a long time: from several days to\r\nseveral weeks, depending on network bandwidth, the state of the source data\r\nservers, and (possibly) star positions.\r\n\r\n### Download CLI\r\n\r\nTo download weather and climate data run:\r\n\r\n```sh\r\npython3 -m weatheasy.download -d STORE {cfs2,cmip6}\r\n```\r\n\r\nWhere `STORE` can be a local path or an S3 link in format\r\n`s3://<bucket>/<prefix>`.\r\n\r\nFor S3 you need to export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. For\r\nany not-AWS S3 storages you also need to export `AWS_ENDPOINT_URL_S3`. See the\r\n[Boto3 docs](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables)\r\nfor details.\r\n\r\nOptionally you can provide a local path to `--download-dir` to preserve\r\noriginal downloaded files (GRIB2 for CFSv2 and NetCDF for CMIP6).\r\n\r\nA full example for CFSv2:\r\n\r\n```sh\r\npython3 -m weatheasy.download -d s3://weatheasy/zarr --download-dir ./downloads cfs2\r\n```\r\n\r\nTo display the full help message, run:\r\n\r\n```sh\r\npython3 -m weatheasy.download -h\r\n```\r\n\r\n### Query CLI\r\n\r\nTo query downloaded data run:\r\n\r\n```sh\r\npython3 -m weatheasy -d STORE -o PATH {cfs2,cmip6} begin end latitude longitude var [var ...]\r\n```\r\n\r\nWhere:\r\n\r\n - `STORE` is the same as for downloading\r\n - `PATH` is a path to write results to (by default, results are output to\r\n console)\r\n - `begin`, `end` are the date range boundaries in ISO format (yyyy-mm-dd)\r\n - `latitude`, `longitude` are target coordinates in EPSG:4326 coordinate\r\n reference system (decimal degrees WGS84)\r\n\r\nThe command line must ends with a space separated list of target variables to\r\nquery. To print a full list of available variables run:\r\n\r\n```sh\r\npython3 -m weatheasy list-vars\r\n```\r\n\r\nA full example for CFSv2, Moscow:\r\n\r\n```sh\r\npython3 -m weatheasy -d s3://weatheasy/zarr cfs2 \\\r\n 2024-01-01 2024-01-31 \\\r\n 55.75222 37.61556 \\\r\n TMIN TMAX TMP\r\n```\r\n\r\nTo display the full help message, run:\r\n\r\n```sh\r\npython3 -m weatheasy -h\r\npython3 -m weatheasy cfs2 -h\r\npython3 -m weatheasy cmip6 -h\r\n```\r\n\r\n### Web API\r\n\r\nAfter [configuring](#configuration) launch the web application with:\r\n\r\n```sh\r\nuvicorn weatheasy.web:app\r\n```\r\n\r\nBy default it would be listening for incoming requests at\r\nhttp://127.0.0.1:8000.\r\n\r\nInteractive API docs are available at\r\nhttp://127.0.0.1:8000/docs.\r\n\r\nAlternative API docs are available at\r\nhttp://127.0.0.1:8000/redoc.\r\n\r\nRead the [Uvicorn docs](https://www.uvicorn.org/deployment/)\r\nfor a full list of supported arguments and options.\r\n\r\n### Docker\r\n\r\nWe provide [Docker images](https://github.com/AgroDT/WeathEasy/pkgs/container/weatheasy)\r\nwith all installed dependencies to run WeathEasy. Pull it with:\r\n\r\n```sh\r\ndocker pull ghcr.io/agrodt/weatheasy\r\n```\r\n\r\nThe default entry point is the web API. Redefine it to use WeathEasy CLI. For\r\nexample, to download CFSv2 data with docker run:\r\n\r\n```sh\r\ndocker run --rm -it \\\r\n --entrypoint python \\\r\n ghcr.io/agrodt/weatheasy \\\r\n -m weatheasy.download \\\r\n -d s3://weatheasy/zarr \\\r\n cfs2\r\n```\r\n\r\nFind an example for Docker Compose at [examples/docker-compose](examples/docker-compose).\r\n\r\n## Development\r\n\r\nWeathEasy is written in Python and managed by [Rye](https://rye.astral.sh/).\r\nAfter cloning this repository, initialize the development environment with:\r\n\r\n```sh\r\nrye sync --all-features\r\n```\r\n\r\nWe also recommend to install and use pre-commit:\r\n\r\n```sh\r\nrye tools install pre-commit\r\npre-commit install\r\n```\r\n\r\nYou can develop WeathEasy with locally running S3-compatible object storage\r\n[MinIO](https://min.io/). Launch it with:\r\n\r\n```sh\r\ndocker compose -f compose.dev.yml up -d\r\n```\r\n\r\nAlso you need to export next variables (see [.example.env](./.example.env)):\r\n\r\n```sh\r\nexport AWS_ENDPOINT_URL_S3=http://127.0.0.1:9000\r\nexport AWS_ACCESS_KEY_ID=minioadmin\r\nexport AWS_SECRET_ACCESS_KEY=minioadmin\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A service for easy weather data acquiring",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/AgroDT/WeathEasy",
"Issues": "https://github.com/AgroDT/WeathEasy/issues",
"Repository": "https://github.com/AgroDT/WeathEasy.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80f3cbe56ac61a1b7052eb4c7e372aa9f01c55723acc1f1012c55094872bc4c5",
"md5": "288ce4cb1ecb42983dba57b3abe26c26",
"sha256": "8e55eb6b28155635c81b80f7285c207763cd1b28943e5db8e54586007d36f9eb"
},
"downloads": -1,
"filename": "weatheasy-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "288ce4cb1ecb42983dba57b3abe26c26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 20412,
"upload_time": "2024-09-03T10:24:06",
"upload_time_iso_8601": "2024-09-03T10:24:06.429063Z",
"url": "https://files.pythonhosted.org/packages/80/f3/cbe56ac61a1b7052eb4c7e372aa9f01c55723acc1f1012c55094872bc4c5/weatheasy-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7277bd868a81ae5237973c4d4b5251238daddb9d0e199069eecb0b66bec67632",
"md5": "33b416db79c7b6a155a4e78e0a7c5313",
"sha256": "7c60aa1f039c75f240df08900ff70625f7b1ebc7c705d206509792b1dfed512e"
},
"downloads": -1,
"filename": "weatheasy-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "33b416db79c7b6a155a4e78e0a7c5313",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 20854,
"upload_time": "2024-09-03T10:24:07",
"upload_time_iso_8601": "2024-09-03T10:24:07.828276Z",
"url": "https://files.pythonhosted.org/packages/72/77/bd868a81ae5237973c4d4b5251238daddb9d0e199069eecb0b66bec67632/weatheasy-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-03 10:24:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AgroDT",
"github_project": "WeathEasy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "weatheasy"
}
