Metadata-Version: 2.1
Name: meteo-hub-cli
Version: 1.3
Summary: meteo-hub client application
Home-page: https://gitlab.hpc.cineca.it/mistral/meteo-hub-cli
Author-email: Davide Cesari <dcesari@arpae.it>
Project-URL: Homepage, https://gitlab.hpc.cineca.it/mistral/meteo-hub-cli
Project-URL: Issues, https://gitlab.hpc.cineca.it/mistral/meteo-hub-cli/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: AGPLv3
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20.0
Requires-Dist: pika>=1.0.1

# Mistral Meteo-Hub-CLI

Meteo-hub-cli is a client application that allows users to perform the
main operations on the Mistral platform from the command line.

For data users, it provides a number of operations that allow to
download data retrieved by means of an immediate or scheduled data
query prepared interactively on the MeteoHub platform. It also allows
to download pre-defined open data packages and it provides a
wait-and-download operation for users having access to an AMQP
data-ready queue.

Notice that the command-line client, at the moment, does not allow to
perform or schedule data queries, these have to be prepared
interactively through the web interface.

For data providers, it implements a `send` operation that allows to
publish data directly to the MeteoHub AMQP broker.

## Installation from source

* Clone this project
  ```
  $ git clone https://gitlab.hpc.cineca.it/mistral/meteo-hub-cli.git
  ```
* create a virtual environment (if needed)
  ```
  $ python3 -mvenv .venv
  $ source .venv/bin/activate
  ``` 
* install project and its dependencies
  ```
  $ pip install .
  ```

## Installation from a precompiled package

For GNU/Linux distributions Fedora 40, Rocky 8 and Rocky 9, pre-built
rpm packages are available from Arpae-SIMC copr repository. The
installing procedure is the following:

```
# enable Arpae-SIMC copr repository
dnf copr enable simc/stable
# install package and its dependencies
dnf install python3-meteo-hub-cli
```

## Creating the configuration file

Before runnng the program, the file `config.ini` has to be created
with the required user credentials. The file provided in the
distribution can be used as an example. The `AMQP` section, defining
the credentials and the characteristics of the user AMQP, is required
only for running the `send` command and the `waitanddl` and the `wait`
commands. The `Meteohub` section is needed for logging into the portal
(it contains the same credentials used for interactive web login).

An alternative configuration file can be chosen with the
`--configfile` command-line option.

The AMQP credentials, at the moment, cannot be created autonomously
online, but they can be obtained only by submitting a request to the
MeteoHub platform managers.

## Running the program

The meteo-hub-cli program requires to specify on the command-line the
desired subcommand to be performed and possibly extra arguments
required by the subcommands. The lines of output which are suitable
for being interpreted by a batch script are in the form of text tables
with the character `|` as a separator.

The general and subcommand-specific help messages can be obtained by:
```
$ meteo-hub-cli --help
$ meteo-hub-cli <subcommand> --help
```

### Informational subcommands

```
    version             Print program version
    settings            Print program configuration
```

### http connection subcommands:

```
    revoketoken         Revoke the meteohub authentication token locally
                        stored
```

### Subcommands for dataset access

```
    reqls               List all the meteohub request instances of the user
    reqdl               Download the output of a meteohub request instance
    schedls             List all the meteohub scheduled request instances of
                        the user
    scheddl             Download the output of a meteohub scheduled request
                        instance
    schedrm             Remove a scheduled request instance and its associated
                        output data
    data                Download a meteohub resource by name
    dsls                List all the datasets available on the server
    odls                List opendata files available for a specific dataset
                        for all reference times
    odata               Download a meteohub opendata resource by name
    oddl                Download a meteohub opendata resource for a specific
                        dataset and reference time
```

These are the main subcommands for interacting with the meteohub
dataset archive. They are suitable for one-time data requests, for
scheduled real-time requests and for downloading open-data predefined
packages. In the first two cases the requests have to be preliminarly
prepared by the user in an interactive way through a web browser. The
following sections present 3 typical examples.

#### Downloading data from a one-time request

```
# list the requests of the user
$ meteo-hub-cli reqls
|anicequery|data-12345678-abcd.grib|
|anotherquery|data-87654321-dcba.grib|
# download by request name
$ meteo-hub-cli reqdl anicequery
# the file is there
$ ls -l
-rw-rw-r-- 1 gverdi gverdi 33893 Jan 28 12:35 data-12345678-abcd.grib
```

#### Downloading data from a scheduled request

```
# list the scheduled requests of the user
$ meteo-hub-cli schedls
|anicequery|data-12345678-abcd.grib|202101280000|
|anotherquery|data-43218765-badc.grib|202101280000|
|anotherquery|data-87654321-dcba.grib|202101281200|
# download by request name and reference time
$ meteo-hub-cli --output today.grib scheddl anotherquery:202101281200
|data-87654321-dcba.grib|today.grib|anotherquery|202101281200|
$ ls -l
# the renamed file is there
-rw-rw-r-- 1 gverdi gverdi 33893 Jan 28 12:35 today.grib
# remove the file on the server to free up space
$ meteo-hub-cli schedrm anotherquery:202101281200
```

#### Downloading a predefined open data package

```
# list the available datasets
$ meteo-hub-cli dsls
|GLOBO-ISAC|FOR|grib|
|ICON-2I_FCENS|FOR|grib|
|ICON-2I_RUC|FOR|grib|
|ICON-2I_all2km|FOR|grib|
|meteonetwork|OBS|bufr|
|MOLOCH-ISAC|FOR|grib|
|multim-forecast|FOR|bufr|
|open-trentino|OBS|bufr|
|SWAN-CAM|FOR|grib|
# list the available packages for the desired dataset
$ meteo-hub-cli odls GLOBO-ISAC
|202502280000|data-20250228T083245Z-43ffcfa4-3c04-4f21-a9ba-948ad348fde3.grib|
|202502270000|data-20250227T083354Z-18c3035c-dfd7-4c3b-add7-24233b8bd4b9.grib|
|202502260000|data-20250226T083358Z-09d207ad-21c0-458f-9c0c-3270f2d77964.grib|
# download the package by dataset name and reference time
$ meteo-hub-cli oddl GLOBO-ISAC:202502270000
```

### Subcommands for interacting with AMQP queues

```
    waitanddl           Wait for a data-ready signal from the configured AMQP
                        queue and download data
    wait                Wait for a data-ready signal from the configured AMQP
                        queue and print id of available data
    send                Send a file to the configured AMQP queue
```

The first two subcommands wait for a "data ready" signal generated by
a one-time or scheduled data query set up on the MeteoHub platform,
for which the "Data Pushing" option was selected; in both cases the
program blocks in an infinite waiting loop for new signals.
`waitanddl` will download each file as soon as a signal is received,
then resume waiting, `wait` will only print on stdout the name of each
user file signaled by the platform and resume waiting.

The `send` command is used for publishing data in real time (tipically
observations) to the MeteoHub AMQP broker by authorised data
providers.
