mlso-api-client 0.3.0__tar.gz

mlso_api_client-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NSF National Center for Atmospheric Research
+
+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.

mlso_api_client-0.3.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: mlso-api-client
+Version: 0.3.0
+Summary: Python package providing a client to access MLSO data
+Author-email: Michael Galloy <mgalloy@ucar.edu>
+License-Expression: BSD-3-Clause
+Project-URL: homepage, https://www2.hao.ucar.edu/mlso
+Project-URL: repository, https://github.com/NCAR/mlso-api-client
+Project-URL: documentation, https://mlso-api-client.readthedocs.io/en/latest/
+Project-URL: issues, https://github.com/NCAR/mlso-api-client/issues
+Project-URL: changelog, https://github.com/NCAR/mlso-api-client/blob/master/CHANGELOG.md
+Keywords: webservice,Mauna Loa Solar Observatory,MLSO,solar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: watchdog; extra == "dev"
+Requires-Dist: Sphinx; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest-runner; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Dynamic: license-file
+
+# mlso-api-client
+
+This package contains Python and IDL clients for accessing MLSO data via the
+MLSO data web API.
+
+## Installation
+
+### Installing from PyPI
+
+The easiest way to install the MLSO API client is via the released versions on
+PyPI. This is the recommended method for most users.
+
+```console
+pip install mlso-api-client
+```
+
+If you want to upgrade an existing installation, do:
+
+```console
+pip install -U mlso-api-client
+```
+
+
+### Installing from source
+
+The source code can be found on the [repo's GitHub page]. Use git or download
+a ZIP file with contents of the source.
+
+[repo's GitHub page]: https://github.com/NCAR/mlso-api-client
+
+Once you have the source code, install the Python portion of the package:
+
+```console
+cd mlso-api-client
+pip install .
+```
+
+If you intend to make changes to the code, install the dev requirements and
+allow changes to the code to automatically be used:
+
+```console
+pip install -e .[dev]
+```
+
+For IDL, simply put the `idl/` directory in your `IDL_PATH`.
+
+
+## Usage
+
+### Command-line interface
+
+Installing the Python package, should install a command-line utility to query
+and download MLSO data, the `mlsoapi` script.
+
+```console
+$ mlsoapi --help
+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
+```
+
+To determine the instruments with data available via the API, use the
+"instruments" sub-command:
+
+```console
+$ mlsoapi instruments
+ID       Instrument name                              Dates available
+-------- -------------------------------------------- -----------------------
+kcor     COSMO K-Coronagraph (KCor)                   2013-09-30...2025-03-24
+ucomp    Upgraded Coronal Multi-Polarimeter (UCoMP)   2021-07-15...2025-03-24
+```
+
+New data for existing and new instruments will be added to the API as possible.
+Submit requests via the [Issues].
+
+[Issues]: https://github.com/NCAR/mlso-api-client/issues
+
+Each instrument has various products available:
+
+```console
+$ mlsoapi products --instrument ucomp
+ID            Title                  Description
+------------- ---------------------- -------------------------------------------------------
+l1            Level 1                IQUV and backgrounds for various wavelengths
+intensity     Level 1 intensity      intensity-only level 1
+mean          Level 1 mean           mean of level 1 files
+median        Level 1 median         median of level 1 files
+sigma         Level 1 sigma          standard deviation of level 1 files
+l2            Level 2                level 2 products
+l2average     Level 2 average        mean, median, standard deviation of level 2 files
+density       Density                density
+dynamics      Dynamics               level 2 dynamics products
+polarization  Polarization           level 2 polarization products
+all           All                    all products
+```
+
+### Python API
+
+TODO: example of using the Python API
+
+
+### IDL API
+
+TODO: example using the IDL routines
+
+
+### API endpoints
+
+To use the webservice API directly from any language, see the [API Endpoints] wiki
+page.
+
+[API Endpoints]: https://github.com/NCAR/mlso-api-client/wiki/API-endpoints

mlso_api_client-0.3.0/README.md

@@ -0,0 +1,127 @@
+# mlso-api-client
+
+This package contains Python and IDL clients for accessing MLSO data via the
+MLSO data web API.
+
+## Installation
+
+### Installing from PyPI
+
+The easiest way to install the MLSO API client is via the released versions on
+PyPI. This is the recommended method for most users.
+
+```console
+pip install mlso-api-client
+```
+
+If you want to upgrade an existing installation, do:
+
+```console
+pip install -U mlso-api-client
+```
+
+
+### Installing from source
+
+The source code can be found on the [repo's GitHub page]. Use git or download
+a ZIP file with contents of the source.
+
+[repo's GitHub page]: https://github.com/NCAR/mlso-api-client
+
+Once you have the source code, install the Python portion of the package:
+
+```console
+cd mlso-api-client
+pip install .
+```
+
+If you intend to make changes to the code, install the dev requirements and
+allow changes to the code to automatically be used:
+
+```console
+pip install -e .[dev]
+```
+
+For IDL, simply put the `idl/` directory in your `IDL_PATH`.
+
+
+## Usage
+
+### Command-line interface
+
+Installing the Python package, should install a command-line utility to query
+and download MLSO data, the `mlsoapi` script.
+
+```console
+$ mlsoapi --help
+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
+```
+
+To determine the instruments with data available via the API, use the
+"instruments" sub-command:
+
+```console
+$ mlsoapi instruments
+ID       Instrument name                              Dates available
+-------- -------------------------------------------- -----------------------
+kcor     COSMO K-Coronagraph (KCor)                   2013-09-30...2025-03-24
+ucomp    Upgraded Coronal Multi-Polarimeter (UCoMP)   2021-07-15...2025-03-24
+```
+
+New data for existing and new instruments will be added to the API as possible.
+Submit requests via the [Issues].
+
+[Issues]: https://github.com/NCAR/mlso-api-client/issues
+
+Each instrument has various products available:
+
+```console
+$ mlsoapi products --instrument ucomp
+ID            Title                  Description
+------------- ---------------------- -------------------------------------------------------
+l1            Level 1                IQUV and backgrounds for various wavelengths
+intensity     Level 1 intensity      intensity-only level 1
+mean          Level 1 mean           mean of level 1 files
+median        Level 1 median         median of level 1 files
+sigma         Level 1 sigma          standard deviation of level 1 files
+l2            Level 2                level 2 products
+l2average     Level 2 average        mean, median, standard deviation of level 2 files
+density       Density                density
+dynamics      Dynamics               level 2 dynamics products
+polarization  Polarization           level 2 polarization products
+all           All                    all products
+```
+
+### Python API
+
+TODO: example of using the Python API
+
+
+### IDL API
+
+TODO: example using the IDL routines
+
+
+### API endpoints
+
+To use the webservice API directly from any language, see the [API Endpoints] wiki
+page.
+
+[API Endpoints]: https://github.com/NCAR/mlso-api-client/wiki/API-endpoints

mlso_api_client-0.3.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "mlso-api-client"
+version = "0.3.0"
+description = "Python package providing a client to access MLSO data"
+authors = [
+  { name="Michael Galloy", email="mgalloy@ucar.edu" },
+]
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.7"
+# see classifiers at https://pypi.org/classifiers/
+classifiers = [
+  "Development Status :: 4 - Beta",
+# Development Status :: 5 - Production/Stable
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Natural Language :: English",
+  "Programming Language :: Python",
+]
+keywords = ["webservice", "Mauna Loa Solar Observatory", "MLSO", "solar"]
+dependencies = [
+  "requests",
+  "tqdm"
+]
+
+[project.urls]
+homepage = "https://www2.hao.ucar.edu/mlso"
+repository = "https://github.com/NCAR/mlso-api-client"
+documentation = "https://mlso-api-client.readthedocs.io/en/latest/"
+issues = "https://github.com/NCAR/mlso-api-client/issues"
+changelog = "https://github.com/NCAR/mlso-api-client/blob/master/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pre-commit",
+  "tox",
+  "wheel",
+  "watchdog",
+  "Sphinx",
+  "twine",
+  "coverage",
+  "flake8",
+  "pytest-runner",
+  "black",
+  "sphinx_rtd_theme",
+  "myst-parser",
+]
+
+[project.scripts]
+mlsoapi = "mlso.api:client.main"
+
+[tool.black]
+line-length = 88
+target-version = ['py37']
+include = '\.pyi?$'
+exclude = '''
+
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+  )/
+  | foo.py           # also separately exclude a file named foo.py in
+                     # the root of the project
+)
+'''
+
+[tool.pytest.ini_options]
+# increment the --cov-fail-under as we increase test coverage
+addopts = "--cov-report html:coverage_html --cov-report term-missing --cov-fail-under 80"
+
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"

mlso_api_client-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlso_api_client-0.3.0/src/mlso/api/__init__.py

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+"""This package contains Python and IDL clients for accessing MLSO data via the
+MLSO data web API.
+"""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version("mlso-api-client")

mlso_api_client-0.3.0/src/mlso/api/client.py

@@ -0,0 +1,553 @@
+# -*- coding: utf-8 -*-
+
+"""Module defining the Python and command line client.
+"""
+
+import argparse
+import datetime
+import logging
+import math
+import os
+from pathlib import Path
+from pprint import pformat
+import sys
+import textwrap
+
+import requests
+import tqdm
+
+
+from . import __version__
+
+BASE_URL = "http://api.mlso.ucar.edu:5000"
+API_VERSION = "v1"
+SIGNUP_URL = "https://registration.hao.ucar.edu"
+
+
+# chunk size for downloading files, 1-10M is probably the most efficient size
+# for good speed and reasonable memory usage
+CHUNK_SIZE = 1024 * 1024
+
+session = requests.Session()
+
+# setup default logging, users of this library can set this to their own logger
+# or modify this one to suit their needs
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.StreamHandler())
+logger.setLevel(logging.DEBUG)
+
+
+# API
+
+
+class UserNotFound(Exception):
+    """Exception raised when a username is found in the registration database."""
+
+    pass
+
+
+class ServerError(Exception):
+    """Exception raised when there is a problem with the server not returning a
+    valid result.
+    """
+
+    pass
+
+
+def about(
+    base_url: str = BASE_URL, api_version: str = API_VERSION, verbose: bool = False
+):
+    """Retrieve the results of the `/about` endpoint."""
+    url = f"{base_url}/{api_version}/about"
+    if verbose:
+        logger.debug(f"URL: {url}")
+
+    try:
+        r = requests.get(url)
+    except requests.exceptions.ConnectionError as e:
+        raise ServerError(f"Connection error reaching {url}")
+
+    if not r.ok:
+        j = r.json()
+        msg = j["message"]
+        raise ServerError(f"Server response: {r.status_code} {r.reason} ({msg})")
+
+    j = r.json()
+
+    if verbose:
+        logger.debug(pformat(j))
+
+    return j
+
+
+def instruments(
+    base_url: str = BASE_URL, api_version: str = API_VERSION, verbose: bool = False
+):
+    """Retrieve list of instruments from the `/instruments/{instrument}`
+    endpoint with some of their properties.
+    """
+    url = f"{base_url}/{api_version}/instruments"
+    if verbose:
+        logger.debug(f"URL: {url}")
+
+    try:
+        r = requests.get(url)
+    except requests.exceptions.ConnectionError as e:
+        raise ServerError(f"Connection error reaching {url}")
+
+    if not r.ok:
+        raise ServerError(f"Server response: {r.status_code} {r.reason}")
+
+    instruments = r.json()
+    if verbose:
+        logger.debug(pformat(instruments))
+
+    instruments = sorted(instruments)
+
+    results = []
+
+    for instrument in instruments:
+        url = f"{base_url}/{api_version}/instruments/{instrument}/"
+        if verbose:
+            logger.debug(f"URL: {url}")
+
+        try:
+            r = requests.get(url)
+        except requests.exceptions.ConnectionError as e:
+            raise ServerError(f"Connection error reaching {url}")
+
+        j = r.json()
+
+        if verbose:
+            logger.debug(pformat(j))
+
+        dates = j["dates"]
+        full_name = j["name"]
+        start_date = dates["start-date"]
+        end_date = dates["end-date"]
+
+        i = {
+            "id": instrument,
+            "start-date": start_date,
+            "end-date": end_date,
+            "name": j["name"],
+        }
+        results.append(i)
+
+    return results
+
+
+def products(
+    instrument,
+    base_url: str = BASE_URL,
+    api_version: str = API_VERSION,
+    verbose: bool = False,
+):
+    """Handle retrieving the `/instruments/{instrument}/products` endpoint
+    results. Can raise ServerError if there is a problem with the web request.
+    """
+    url = f"{base_url}/{api_version}/instruments/{instrument}/products"
+    if verbose:
+        logger.debug(f"URL: {url}")
+
+    try:
+        r = requests.get(url)
+    except requests.exceptions.ConnectionError as e:
+        raise ServerError(f"Connection error reaching {url}")
+
+    if not r.ok:
+        j = r.json()
+        msg = j["message"]
+        raise ServerError(f"Server response: {r.status_code} {r.reason} ({msg})")
+
+    j = r.json()
+
+    if verbose:
+        logger.debug(pformat(j))
+
+    return j
+
+
+def authenticate(
+    username: str = None,
+    base_url: str = BASE_URL,
+    api_version: str = API_VERSION,
+    verbose: bool = False,
+):
+    """Authenticate username within the session. This must be called before
+    `download_file`.
+    """
+    if username is None:
+        msg = f"username required, sign up at {SIGNUP_URL}"
+        raise UserNotFound(msg)
+    else:
+        url = f"{base_url}/{api_version}/authenticate?username={username}"
+        if verbose:
+            logger.debug(pformat(f"URL: {url}"))
+        try:
+            r = session.get(url)
+        except requests.exceptions.ConnectionError as e:
+            raise ServerError(f"Connection error reaching {url}")
+
+        if not r.ok:
+            if r.status_code == 404:
+                info = r.json()
+                if verbose:
+                    logger.debug(pformat(info))
+                raise UserNotFound(info["message"])
+            else:
+                j = r.json()
+                msg = j["message"]
+                raise ServerError(
+                    f"Server response: {r.status_code} {r.reason} ({msg})"
+                )
+
+
+def download_file(file, output_dir):
+    """Download a single file to the given output directory. The `file` argument
+    is a dict with fields "url" and "filename". `output_dir` is simply the
+    directory to put the downloaded file. Can raise ServerError if there is a
+    problem with the web request.
+    """
+    url = file["url"]
+    try:
+        r = session.get(url, stream=True, cookies=session.cookies.get_dict())
+    except requests.exceptions.ConnectionError as e:
+        raise ServerError(f"Connection error reaching {url}")
+
+    if not r.ok:
+        raise ServerError(f"Server response: {r.status_code} {r.reason}")
+
+    path = Path(output_dir) / file["filename"]
+
+    with open(path, "wb") as handle:
+        for data in r.iter_content(chunk_size=CHUNK_SIZE):
+            handle.write(data)
+    return path
+
+
+def files(
+    instrument: str,
+    product: str,
+    filters: list[dict[str, str]] | None = None,
+    base_url: str = BASE_URL,
+    api_version: str = API_VERSION,
+    verbose=False,
+):
+    """Handle retrieving the `/instruments/{instrument}/products/{product}`
+    endpoint results. Can raise ServerError if there is a problem with the web
+    request. Use `download_file` to download the file(s) returned with routine.
+    """
+    url = f"{base_url}/{api_version}/instruments/{instrument}/products/{product}"
+
+    if len(filters) > 0:
+        url += "?" + "&".join([f"{f}={filters[f]}" for f in filters])
+
+    if verbose:
+        logger.debug(f"URL: {url}")
+
+    try:
+        r = requests.get(url)
+    except requests.exceptions.ConnectionError as e:
+        raise ServerError(f"Connection error reaching {url}")
+
+    if not r.ok:
+        j = r.json()
+        msg = j["message"]
+        raise ServerError(f"Server response: {r.status_code} {r.reason} ({msg})")
+
+    j = r.json()
+    if verbose:
+        logger.debug(pformat(j))
+
+    return j
+
+
+# Command line interface sub-command handlers
+
+
+def _about(args):
+    """Handle printing the `/about` endpoint results for the command line
+    interface.
+    """
+    try:
+        about_response = about(args.base_url, verbose=args.verbose)
+        server_version = about_response["version"]
+        documentation_url = about_response["documentation"]
+        print(
+            f"server version: {server_version}, client version: {__version__}"
+        )
+        print(f"documentation: {documentation_url}")
+    except ServerError as e:
+        print(e)
+
+
+def _instruments(args):
+    """Handle printing the `/instruments` endpoint results for the command line
+    interface.
+    """
+    try:
+        instruments_response = instruments(args.base_url, verbose=args.verbose)
+    except ServerError as e:
+        print(e)
+        return
+
+    print(f"{'ID':8s} {'Instrument name':44s} Dates available")
+    print(f"{'-' * 8} {'-' * 44} {'-' * 23}")
+
+    for i in instruments_response:
+        instrument = i["id"]
+        instrument_name = i["name"]
+        start_date = i["start-date"][:10]
+        end_date = i["end-date"][:10]
+
+        print(f"{instrument:8s} {instrument_name:44s} {start_date}...{end_date}")
+
+
+def _products(args):
+    """Handle printing the `/instruments/{instrument}/products` endpoint
+    results for the command line interface.
+    """
+    try:
+        products_response = products(
+            args.instrument, base_url=args.base_url, verbose=args.verbose
+        )
+    except ServerError as e:
+        print(e)
+        return
+
+    print(f"{'ID':13s} {'Title':22s} {'Description'}")
+    print(f"{'-' * 13} {'-' * 22} {'-' * 55}")
+    for p in products_response["products"]:
+        title = p["title"]
+        product_id = p["id"]
+        description = textwrap.wrap(p["description"], width=55)
+        if len(description) == 0:
+            description = [""]
+        for description_line in description:
+            print(f"{product_id:13s} {title:22s} {description_line}")
+            product_id = ""
+            title = ""
+            name = ""
+
+
+def _download_files(
+    base_url: str,
+    filelist: list,
+    output_dir: Path,
+    username: str,
+    verbose: bool = False,
+    quiet: bool = False,
+):
+    """Download the given files to an output directory. The `files` argument is
+    a list of dicts with fields "url" and "filename".
+    """
+    if not output_dir.is_dir():
+        if verbose:
+            print(f"creating output path {output_dir}")
+        os.makedirs(output_dir)
+
+    try:
+        authenticate(username, base_url=base_url, verbose=verbose)
+    except UserNotFound as e:
+        print(e)
+        sys.exit(1)
+    except ServerError as e:
+        print(e)
+        sys.exit(1)
+
+    if quiet:
+        iterable_files = filelist
+        message = print
+    else:
+        iterable_files = tqdm.tqdm(filelist)
+        message = tqdm.tqdm.write
+
+    n_failed = 0
+    for f in iterable_files:
+        try:
+            filepath = download_file(f, output_dir)
+        except ServerError as e:
+            message(f"{f['url']} failed")
+            n_failed += 1
+
+    if n_failed > 0:
+        print(f"{n_failed} failed downloads")
+
+
+unit_list = list(zip(["B", "KB", "MB", "GB", "TB", "PB"], [0, 0, 1, 2, 2, 2]))
+
+
+def sizeof_fmt(n_bytes: int) -> str:
+    """Human friendly file size"""
+    if n_bytes == 0:
+        return "0 B"
+    if n_bytes >= 1:
+        exponent = min(int(math.log(n_bytes, 1024)), len(unit_list) - 1)
+        quotient = float(n_bytes) / 1024**exponent
+        unit, num_decimals = unit_list[exponent]
+        format_string = "{:.%sf} {}" % (num_decimals)
+        return format_string.format(quotient, unit)
+
+
+def _files(args):
+    """Handle printing the `/instruments/{instrument}/products/{product}`
+    endpoint results, optionally downloading the files.
+    """
+    filters = {}
+
+    if args.wave_region is not None:
+        filters["wave-region"] = args.wave_region
+
+    if args.obs_plan is not None:
+        filters["obs-plan"] = args.obs_plan
+
+    if args.start_date is not None:
+        filters["start-date"] = args.start_date
+
+    if args.end_date is not None:
+        filters["end-date"] = args.end_date
+
+    if args.carrington_rotation is not None:
+        filters["cr"] = args.carrington_rotation
+
+    if args.every is not None:
+        filters["every"] = args.every
+
+    try:
+        files_response = files(
+            args.instrument,
+            args.product,
+            filters,
+            base_url=args.base_url,
+            verbose=args.verbose,
+        )
+    except ServerError as e:
+        print(e)
+        return
+
+    if args.verbose:
+        instrument = files_response["instrument"]
+        product = files_response["product"]
+        start_date = files_response["start-date"]
+        end_date = files_response["end-date"]
+        filesize = sizeof_fmt(files_response["total_filesize"])
+        print(f"Instrument : {instrument}")
+        print(f"Product    : {product}")
+        print(f"Start date : {start_date}")
+        print(f"End date   : {end_date}")
+        print(f"Filesize   : {filesize}")
+
+    filelist = files_response["files"]
+    if args.download:
+        _download_files(
+            args.base_url,
+            filelist,
+            Path(args.output_dir),
+            args.username,
+            verbose=args.verbose,
+            quiet=args.quiet,
+        )
+    else:
+        if len(filelist) > 0:
+            if args.verbose:
+                print()
+            max_filename_len = max([len(f["filename"]) for f in filelist])
+            print(
+                f"{'Date/time':20s} {'Instrument':10s} {'Product':13s} {'Filesize':10s} {'Filename'}"
+            )
+            print(
+                f"{'-' * 20} {'-' * 10} {'-' * 13} {'-' * 10} {'-' * max_filename_len}"
+            )
+            total_filesize = 0
+        for f in filelist:
+            total_filesize += f["filesize"]
+            print(
+                f"{f['date-obs']:20s} {f['instrument']:10s} {f['product']:13s} {sizeof_fmt(f['filesize']):>10s} {f['filename']}"
+            )
+        if len(filelist) > 1:
+            print(
+                f"{'-' * 20} {'-' * 10} {'-' * 13} {'-' * 10} {'-' * max_filename_len}"
+            )
+            n_files = f"{len(filelist)} files"
+            print(f"{n_files:45s} {sizeof_fmt(total_filesize):>10s} {''}")
+
+
+def _print_help(args):
+    """Print the usage help for the command-line utility."""
+    args.parser.print_help()
+
+
+def main():
+    """Entry point for MLSO API command-line utility."""
+    name = f"MLSO API command line interface (mlso-api-client {__version__})"
+    parser = argparse.ArgumentParser(description=name)
+
+    parser.add_argument("-v", "--version", action="version", version=name)
+
+    # show help if no sub-command given
+    parser.set_defaults(func=_print_help, parser=parser)
+
+    parser.add_argument(
+        "-u", "--base-url", help="base URL for MLSO API", default=BASE_URL
+    )
+    parser.add_argument("--verbose", help="output warnings", action="store_true")
+    parser.add_argument(
+        "-q", "--quiet", help="surpress informational messages", action="store_true"
+    )
+
+    subparsers = parser.add_subparsers(help="sub-command help")
+
+    instruments_parser = subparsers.add_parser("instruments", help="MLSO instruments")
+    instruments_parser.set_defaults(func=_instruments, parser=instruments_parser)
+
+    products_parser = subparsers.add_parser("products", help="MLSO instruments")
+    products_parser.add_argument("-i", "--instrument", help="instrument", default=None)
+    products_parser.set_defaults(func=_products, parser=products_parser)
+
+    files_parser = subparsers.add_parser("files", help="MLSO data files")
+    files_parser.add_argument("-i", "--instrument", help="instrument", default=None)
+    files_parser.add_argument("-p", "--product", help="product", default=None)
+    files_parser.add_argument(
+        "--wave-region", help="wave region, e.g., 1074, 1079, etc.", default=None
+    )
+    files_parser.add_argument(
+        "--obs-plan", help="observing plan: synoptic or waves", default=None
+    )
+    files_parser.add_argument("-s", "--start-date", help="start date", default=None)
+    files_parser.add_argument("-e", "--end-date", help="end date", default=None)
+    files_parser.add_argument(
+        "-c", "--carrington-rotation", help="Carrington Rotation number", default=None
+    )
+    files_parser.add_argument(
+        "--every", help="time to choose 1 file from", default=None
+    )
+    files_parser.add_argument(
+        "-d", "--download", help="download the displayed files", action="store_true"
+    )
+    files_parser.add_argument(
+        "-u", "--username", help="email already registered at HAO website", default=None
+    )
+    files_parser.add_argument(
+        "-o", "--output-dir", help="output directory for downloaded files", default="."
+    )
+    files_parser.set_defaults(func=_files, parser=files_parser)
+
+    # parse args and call appropriate sub-command
+    args = parser.parse_args()
+
+    if args.verbose:
+        _about(args)
+        print()
+
+    if parser.get_default("func"):
+        try:
+            args.func(args)
+        except KeyboardInterrupt:
+            print()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: mlso-api-client
+Version: 0.3.0
+Summary: Python package providing a client to access MLSO data
+Author-email: Michael Galloy <mgalloy@ucar.edu>
+License-Expression: BSD-3-Clause
+Project-URL: homepage, https://www2.hao.ucar.edu/mlso
+Project-URL: repository, https://github.com/NCAR/mlso-api-client
+Project-URL: documentation, https://mlso-api-client.readthedocs.io/en/latest/
+Project-URL: issues, https://github.com/NCAR/mlso-api-client/issues
+Project-URL: changelog, https://github.com/NCAR/mlso-api-client/blob/master/CHANGELOG.md
+Keywords: webservice,Mauna Loa Solar Observatory,MLSO,solar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: watchdog; extra == "dev"
+Requires-Dist: Sphinx; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pytest-runner; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: sphinx_rtd_theme; extra == "dev"
+Requires-Dist: myst-parser; extra == "dev"
+Dynamic: license-file
+
+# mlso-api-client
+
+This package contains Python and IDL clients for accessing MLSO data via the
+MLSO data web API.
+
+## Installation
+
+### Installing from PyPI
+
+The easiest way to install the MLSO API client is via the released versions on
+PyPI. This is the recommended method for most users.
+
+```console
+pip install mlso-api-client
+```
+
+If you want to upgrade an existing installation, do:
+
+```console
+pip install -U mlso-api-client
+```
+
+
+### Installing from source
+
+The source code can be found on the [repo's GitHub page]. Use git or download
+a ZIP file with contents of the source.
+
+[repo's GitHub page]: https://github.com/NCAR/mlso-api-client
+
+Once you have the source code, install the Python portion of the package:
+
+```console
+cd mlso-api-client
+pip install .
+```
+
+If you intend to make changes to the code, install the dev requirements and
+allow changes to the code to automatically be used:
+
+```console
+pip install -e .[dev]
+```
+
+For IDL, simply put the `idl/` directory in your `IDL_PATH`.
+
+
+## Usage
+
+### Command-line interface
+
+Installing the Python package, should install a command-line utility to query
+and download MLSO data, the `mlsoapi` script.
+
+```console
+$ mlsoapi --help
+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
+```
+
+To determine the instruments with data available via the API, use the
+"instruments" sub-command:
+
+```console
+$ mlsoapi instruments
+ID       Instrument name                              Dates available
+-------- -------------------------------------------- -----------------------
+kcor     COSMO K-Coronagraph (KCor)                   2013-09-30...2025-03-24
+ucomp    Upgraded Coronal Multi-Polarimeter (UCoMP)   2021-07-15...2025-03-24
+```
+
+New data for existing and new instruments will be added to the API as possible.
+Submit requests via the [Issues].
+
+[Issues]: https://github.com/NCAR/mlso-api-client/issues
+
+Each instrument has various products available:
+
+```console
+$ mlsoapi products --instrument ucomp
+ID            Title                  Description
+------------- ---------------------- -------------------------------------------------------
+l1            Level 1                IQUV and backgrounds for various wavelengths
+intensity     Level 1 intensity      intensity-only level 1
+mean          Level 1 mean           mean of level 1 files
+median        Level 1 median         median of level 1 files
+sigma         Level 1 sigma          standard deviation of level 1 files
+l2            Level 2                level 2 products
+l2average     Level 2 average        mean, median, standard deviation of level 2 files
+density       Density                density
+dynamics      Dynamics               level 2 dynamics products
+polarization  Polarization           level 2 polarization products
+all           All                    all products
+```
+
+### Python API
+
+TODO: example of using the Python API
+
+
+### IDL API
+
+TODO: example using the IDL routines
+
+
+### API endpoints
+
+To use the webservice API directly from any language, see the [API Endpoints] wiki
+page.
+
+[API Endpoints]: https://github.com/NCAR/mlso-api-client/wiki/API-endpoints

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/mlso/api/__init__.py
+src/mlso/api/client.py
+src/mlso_api_client.egg-info/PKG-INFO
+src/mlso_api_client.egg-info/SOURCES.txt
+src/mlso_api_client.egg-info/dependency_links.txt
+src/mlso_api_client.egg-info/entry_points.txt
+src/mlso_api_client.egg-info/requires.txt
+src/mlso_api_client.egg-info/top_level.txt

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mlsoapi = mlso.api:client.main

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/requires.txt

@@ -0,0 +1,17 @@
+requests
+tqdm
+
+[dev]
+pytest
+pre-commit
+tox
+wheel
+watchdog
+Sphinx
+twine
+coverage
+flake8
+pytest-runner
+black
+sphinx_rtd_theme
+myst-parser

mlso_api_client-0.3.0/src/mlso_api_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+mlso