mlso-api-client package

Submodules

mlso.api.client module

Module defining the Python and command-line client. The programmatic interface is typically used like:

>>> from mlso.api import client
>>> client.about()
{'documentation': 'https://mlso-api-client.readthedocs.io/en/latest/',
'homepage': 'https://www2.hao.ucar.edu/mlso',
'support': 'mlso_data_requests@ucar.edu',
'version': '0.3.1'}

The Unix command-line interface, mlsoapi, is also available:

usage: mlsoapi [-h] [-v] [-u BASE_URL] [--verbose] [-q] {instruments,products,files} ...

MLSO API command line interface (mlso-api-client 1.0.0)

positional arguments:
{instruments,products,files}
                        sub-command help
    instruments         MLSO instruments
    products            MLSO instruments
    files               MLSO data files

options:
-h, --help            show this help message and exit
-v, --version         show program's version number and exit
-u BASE_URL, --base-url BASE_URL
                        base URL for MLSO API
--verbose             output warnings
-q, --quiet           surpress informational messages

exception mlso.api.client.ServerError

Bases: Exception

Exception raised when there is a problem with the server not returning a valid result.

exception mlso.api.client.UserNotFound

Bases: Exception

Exception raised when a username is not found in the registration database.

mlso.api.client.about(base_url: str = 'http://api.mlso.ucar.edu', api_version: str = 'v1', verbose: bool = False)

Retrieve basic facts about the MLSO API server, i.e., the results of the /about endpoint. For example:

>>> client.about()
{'documentation': 'https://mlso-api-client.readthedocs.io/en/latest/',
'homepage': 'https://www2.hao.ucar.edu/mlso',
'support': 'mlso_data_requests@ucar.edu',
'version': '1.0.0'}

about can raise a ServerError if the server response is not valid.

mlso.api.client.authenticate(username: str = None, base_url: str = 'http://api.mlso.ucar.edu', api_version: str = 'v1', verbose: bool = False)

Authenticate username within the session. The username is registered with the MLSO website first. Then authenticate must be called before calling download_file. For example:

>>> client.authenticate(my_email_address)

You only need to call authenticate once per session.

This routine can raise a UserNotFound exception if the username has not already been registered with the MLSO website or a ServerError exception if there is a problem with the web request.

mlso.api.client.download_file(file, output_dir)

Download a single file to the given output directory. The file argument is a dict with at least fields “url” and “filename”. output_dir is simply the directory to put the downloaded file.

>>> from mlso.api import client
>>> client.authenticate(my_email_address)
>>> filters = {"start-date": "2025-3-24", "wave-region": "789"}
>>> files_info = client.files("ucomp", "l2", filters=filters)
>>> for f in files_info["files"]:
...     download_file(f, ".")

Can raise ServerError if there is a problem with the web request.

mlso.api.client.files(instrument: str, product: str, filters: dict[str, str] | None = None, base_url: str | None = 'http://api.mlso.ucar.edu', api_version: str | None = 'v1', verbose=False, client: str | None = 'python')

Retrieve metadata about files from a given instrument/product and filtered by various optional filters, i.e., handle retrieving the results of the /instruments/{instrument}/products/{product} endpoint. For example:

>>> from mlso.api import client
>>> client.files("ucomp", "l2", filters={"start-date": "2025-3-24", "wave-region": "789"})
{'end-date': '2025-03-24T21:03:55',
 'files': [{
    'date-obs': '2025-03-24T20:06:52',
    'filename': '20250324.200652.ucomp.789.l2.fts',
    'filesize': 0,
    'instrument': 'ucomp',
    'obs-plan': 'synoptic-original-lines.cbk',
    'product': 'l2',
    'url': 'http://api.mlso.ucar.edu/v1/download?obsday-id=10136&instrument=ucomp&filename=20250324.200652.ucomp.789.l2.fts',
    'wave-region': '789',
    'wavelengths': 5
 }],
 'instrument': 'ucomp',
 'product': 'l2',
 'start-date': '2025-3-24',
 'total_filesize': 0}

Use download_file to download the file(s) returned with this routine.

The available filters are listed below. Note that some filters are available only for certain instruments.

Parameter	Description
start‑date	Return only files after the “start-date”.
end‑date	Return only files before the “end-date”.
cr	Return only files matching Carrington Rotation number “cr”.
every	Return only a single file for every time period matching “every”. The recognized time periods are: second, minute, hour, day, week, month, quarter, or year (optionally ending in “s”). This parameter is an integer followed by one of these time periods, e.g., every=2hours, every=1day, or every=12hours.
wave‑region	Return only files for the given wave region (UCoMP only). Valid values are “637”, “706”, “789”, 1074”, “1079”.
obs‑plan	Return only files matching the given observing plan, e.g.: “waves” “synoptic” (UCoMP only).

Can raise a ServerError if there is a problem with the web request.

mlso.api.client.instruments(base_url: str = 'http://api.mlso.ucar.edu', api_version: str = 'v1', verbose: bool = False)

Retrieve list of instruments from the /instruments/{instrument} endpoint with some of their properties. For example:

>>> from mlso.api import client
>>> client.instruments()
[{'id': 'kcor',
'start-date': '2013-09-30T18:57:54',
'end-date': '2025-03-24T21:04:20',
'name': 'COSMO K-Coronagraph (KCor)'},
{'id': 'ucomp',
'start-date': '2021-07-15T17:31:43',
'end-date': '2025-03-24T21:03:55',
'name': 'Upgraded Coronal Multi-Polarimeter (UCoMP)'}]

Or:

>>> [i["id"] for i in client.instruments()]
['kcor', 'ucomp']

instruments can raise a ServerError if there is a problem with the web request.

mlso.api.client.main()

Entry point for MLSO API command-line utility.

$ mlsoapi --help
usage: mlsoapi [-h] [-v] [-u BASE_URL] [--verbose] [-q] {instruments,products,files} ...

MLSO API command line interface (mlso-api-client 0.3.2)

positional arguments:
{instruments,products,files}
                        sub-command help
    instruments         MLSO instruments
    products            MLSO instruments
    files               MLSO data files

options:
-h, --help            show this help message and exit
-v, --version         show program's version number and exit
-u BASE_URL, --base-url BASE_URL
                        base URL for MLSO API
--verbose             output warnings
-q, --quiet           surpress informational messages

mlso.api.client.products(instrument, base_url: str = 'http://api.mlso.ucar.edu', api_version: str = 'v1', verbose: bool = False)

Retrieve the available products for the given instruments, i.e., retreive the results of the /instruments/{instrument}/products endpoint. For example:

>>> from mlso.api import client
>>> client.products("ucomp")
{'products': [{'description': 'IQUV and backgrounds for various wavelengths',
'id': 'l1',
'title': 'Level 1'},
{'description': 'intensity-only level 1',
'id': 'intensity',
'title': 'Level 1 intensity'},
{'description': 'mean of level 1 files',
'id': 'mean',
'title': 'Level 1 mean'},
{'description': 'median of level 1 files',
'id': 'median',
'title': 'Level 1 median'},
{'description': 'standard deviation of level 1 files',
'id': 'sigma',
'title': 'Level 1 sigma'},
{'description': 'level 2 products', 'id': 'l2', 'title': 'Level 2'},
{'description': 'mean, median, standard deviation of level 2 files',
'id': 'l2average',
'title': 'Level 2 average'},
{'description': 'density', 'id': 'density', 'title': 'Density'},
{'description': 'level 2 dynamics products',
'id': 'dynamics',
'title': 'Dynamics'},
{'description': 'level 2 polarization products',
'id': 'polarization',
'title': 'Polarization'},
{'description': 'all products', 'id': 'all', 'title': 'All'}]}

And:

>>> [p["id"] for p in client.products("ucomp", base_url=base_url)["products"]]
['l1',
'intensity',
'mean',
'median',
'sigma',
'l2',
'l2average',
'density',
'dynamics',
'polarization',
'all']

products can raise a ServerError if there is a problem with the web request.