"""
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/ site.
**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 :meth:`~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.
**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)
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")
"""
import logging
from jwst.lib.engdb_direct import EngdbDirect
from jwst.lib.engdb_mast import EngdbMast
# Configure logging
logger = logging.getLogger(__name__)
__all__ = ["ENGDB_Service"]
[docs]
def ENGDB_Service(base_url=None, **service_kwargs): # noqa: N802
"""
Provide access to 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