Source code for jwst.lib.engdb_tools

"""Access the JWST Engineering Mnemonic Database

The engineering mnemonics are provided by multiple services, all of which require a level of authentication.

For non-operational use, the providing service is through the MAST AUI website

    https://mast.stsci.edu/portal/Mashup/Clients/jwstedb/jwstedb.html

Authorization can be requested through

    https://auth.mast.stsci.edu/

Interface
=========

The primary entry point is the function `jwst.lib.engdb_tools.ENGDB_Service`.
This function returns a `jwst.lib.engdb_lib.EngdbABC` connection object. Using
this object, values for a mnemonic covering a specified time range can be
retrieved using the `~jwst.lib.engdb_lib.EngdbABC.get_values` method.

By default, only values inclusively between the time end points are returned.
Depending on the frequency a mnemonic is updated, there can be no values. If
values are always desired, the nearest, bracketing values outside the time
range can be requested.

Warning
=======

Many mnemonics are updated very quickly, up to 16Hz. When in doubt, specify a
very short time frame, and request bracketing values. Otherwise, the request
can return a very large amount of data, risking timeout, unnecessary memory
consumption, or access restrictions.

Examples
========

The typical workflow is as follows:

.. code-block:: python

    from jwst.lib.engdb_tools import ENGDB_Service

    service = ENGDB_Service()  # By default, will use the public MAST service.

    values = service.get_values('sa_zattest2', '2021-05-22T00:00:00', '2021-05-22T00:00:01')

Environmental Variables
=======================

ENG_BASE_URL
    If no URL is specified in code or by command line parameters, this value is used.
    If not defined, a default, as defined by the individual services, will be attempted.

MAST_API_TOKEN
    If no token is provided in code or by command line parameters, this value will be used.
    `~jwst.lib.engdb_mast.EngdbMast` service requires a token to be provided.
    See https://auth.mast.stsci.edu/ for more information.

ENG_RETRIES
    Number of attempts to make when connecting to the service. Default is 10.

ENG_TIMEOUT
    Number of seconds before timing out a network connection. Default is 600 seconds (10 minutes)
"""
import logging

from .engdb_direct import EngdbDirect
from .engdb_mast import EngdbMast

# Configure logging
logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())


[docs] def ENGDB_Service(base_url=None, **service_kwargs): """Access the JWST Engineering Database Access can be either through the public MAST API or by direct connection to the database server. Parameters ---------- base_url : str or None. The base url for the engineering RESTful service service_kwargs : dict Service-specific keyword arguments. Refer to the concrete implementations of `~jwst.lib.engdb_lib.EngdbABC`. Returns ------- service : `~jwst.lib.engdb_lib.EngdbABC` The engineering database service to use. """ # Determine the database to use for db_attempt in [EngdbMast, EngdbDirect]: try: service = db_attempt(base_url=base_url, **service_kwargs) except RuntimeError as excp: logger.debug('Service %s cannot use base_url %s.', db_attempt, base_url) logger.debug('Exception: %s', excp) else: # Found the working service. Continue on. break else: raise RuntimeError(f'Base URL of {base_url} cannot be accessed.') # Service is in hand. return service