llama.com.gracedb package¶

Safely import GraceDB, registering a warning if the import fails.

class llama.com.gracedb.GraceDb(*args, **kwargs)¶

Bases: ligo.gracedb.rest.GraceDb

A subclass of ligo.gracedb.rest.GraceDb that refreshes LLAMA GraceDb credentials in the event of an authentication error before retrying requests. Also checks for installed, non-expired credentials before initializing and automatically installs LLAMA keytab and refreshes Kerberos principal if necessary. Only does this if environmental variable LLAMA_GRACEDB_AUTH is set to an S3 key for a valid LIGO robot keytab; otherwise, behaves just like ligo.gracedb.rest.GraceDb (with some extra logging on authentication errors).

ligo.gracedb.rest.GraceDb docstring below:

GraceDb REST client class.

Provides a client object for accessing the GraceDB server API. Various methods are provided for retrieving information about different objects and uploading information.

Lookup of user credentials is done in the following order:

If provided, import X.509 credentials from the certificate-key pair or combined proxy file provided in the cred keyword arg.
If provided, use the username and password provided in the keyword arguments.
If the X509_USER_CERT and X509_USER_KEY environment variables are set, load the corresponding certificate and key.
If the X509_USER_PROXY environment variable is set, load the corresponding proxy file.
Look for a X.509 proxy from ligo-proxy-init in the default location (/tmp/x509up_u${UID}).
Look for a certificate and key file in $HOME/.globus/usercert.pem and $HOME/.globus/userkey.pem.
Look for a username and password for the server in $HOME/.netrc.
Continue with no authentication credentials.

Parameters

url (str, optional) – URL of server API root.
proxy_host (str, optional) – proxy hostname.
proxy_port (str, optional) – proxy port.
cred (tuple or str, optional) – a tuple or list of (/path/to/cert/file, /path/to/key/file) or a single path to a combined proxy file. Used for X.509 authentication only.
username (str, optional) – username for basic auth.
password (str, optional) – password for basic auth.
force_noauth (bool, optional) – set to True if you want to skip credential lookup and use this client without authenticating to the server.
fail_if_noauth (bool, optional) – set to True if you want the client constructor to fail if no authentication credentials are provided or found.
api_version (str, optional) – choose the version of the server API to use. At present, there is only one version, but this argument is provided with the expectation that this will change in the future.
reload_certificate (bool, optional) – if True, your certificate will be checked before each request whether it is within reload_buffer seconds of expiration, and if so, it will be reloaded. Useful for processes which may live longer than the certificate lifetime and have an automated method for certificate renewal. The path to the new/renewed certificate must be the same as for the old certificate.
reload_buffer (int, optional) – buffer (in seconds) for reloading a certificate in advance of its expiration. Only used if reload_certificate is True.

Examples

Instantiate a client to use the production GraceDB server:

>>> g = GraceDb()

Use another GraceDB server:

>>> g = GraceDb(service_url='https://gracedb-playground.ligo.org/api/')

Use a certificate and key in the non-default location:

>>> g = GraceDb(cred=('/path/to/cert/file', '/path/to/key/file'))

event(graceid)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Get information about an individual event.

Args:
graceid (str): GraceDB ID of the event

Returns:
httplib.HTTPResponse

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Example:
>>> g = GraceDb()
>>> event_dict = g.event('T101383').json()

events(query=None, orderby=None, max_results=None, **kwargs)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Search for events which match a query.

Information on forming queries is available here: https://gracedb.ligo.org/documentation/queries.html
Args:
query (str, optional): query string. orderby (str, optional): field to order the results by. max_results (int, optional): maximum number of results to

return (default: all).

Returns:
Iterator[dict]

An iterator which yields individual event dictionaries.

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Example:
>>> g = GraceDb()
>>> for event in g.events('ER5 submitter: "gstlalcbc"'):
...     print(event['graceid'], event['far'], event['gpstime'])

files(object_id, filename='', *args, **kwargs)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Get a list of files or download a file associated with an event or

superevent.

If filename is not provided, get a list of available files associated with the event or superevent. If filename is provided, download the contents of that file.

Args:

object_id (str): event graceid or superevent ID. filename (str, optional): name of file to download.

Returns:

httplib.HTTPResponse

When filename is not specified, response.json() contains a dict with file basename keys and full file URL values. When filename is specified, use response.read() to get the contents of the file.

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status: code >= 400.

Examples:

Get a list of files:

>>> g = GraceDb()
>>> event_files = g.files('T101383').json()
>>> for filename in list(event_files):
...     # do something
...     pass

Get a file’s content:

>>> outfile = open('my_skymap.png', 'w')
>>> r = g.files('T101383', 'skymap.png')
>>> outfile.write(r.read())
>>> outfile.close()

logs(object_id, log_number=None, *args, **kwargs)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Get log entries associated with an event or superevent.

If log_number is specified, only a single log message is returned. Otherwise, all log messages attached to the event or superevent in question are returned.

Args:
object_id (str): event graceid or superevent ID. log_number (int, optional): ID number (N) of the log

entry to retrieve.

Returns:
httplib.HTTPResponse

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Examples:
Get all log messages:
>>> g = GraceDb()
>>> response_dict = g.logs('T101383').json()
>>> print "Num logs = %d" % response_dict['numRows']
>>> log_list = response_dict['log']
>>> for log in log_list:
...     print log['comment']
Get a single log message:
>>> g = GraceDb()
>>> log_info = g.logs('T101383', 10).json()

superevent(superevent_id)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Get information about an individual superevent.

Args:
superevent_id (str): GraceDB ID of the superevent.

Returns:
httplib.HTTPResponse

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Example:
>>> g = GraceDb()
>>> superevent = g.superevent('S181224a').json()

superevents(query='', orderby=None, count=None, columns=None, max_results=None)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Search for superevents which match a query.

Information on forming queries is available here: https://gracedb.ligo.org/documentation/queries.html
Args:
query (str, optional): query string. orderby (str, optional): field to order the results by. count (int, optional): each generator iteration will yield

this many objects (default determined by the server).

columns (list[str], optional): list of attributes to return
for each superevent (default: all).

max_results (int, optional): maximum number of results to
return (default: all).

Returns:
Iterator[dict]

An iterator which yields individual superevent dictionaries.

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Example:
>>> g = GraceDb()
>>> for s in g.superevents(query='is_gw: True', orderby=
... ['-preferred_event'], columns=['superevent_id', 'events']):
...     print(s['superevent_id'])

writeLog(object_id, message, filename=None, filecontents=None, tag_name=[], displayName=[], *args, **kwargs)¶

This method will automatically try to install LIGO proxy credentials if a RuntimeError or ligo.gracedb.exceptions.HTTPError is caught (if GRACEDB_AUTH is set to the S3 key of a valid LIGO robot keytab, set by environmental variable LLAMA_GRACEDB_AUTH).

Original docstring:

Create a new log entry associated with an event or superevent.

Args:
object_id (str): event graceid or superevent ID. message (str): comment to post. filename (str, optional): path to file to be uploaded.

Use '-' to read from stdin.

filecontents (file, optional): handler pointing to a file to
be read and uploaded. If this argument is specified, the contents will be saved as filename on the server.

tag_name (str or list[str], optional): tag name or
list of tag names to be applied to the log message.

displayName (str or list[str], optional): tag display
string or list of display strings for the tag(s) in tag_name. If provided, there should be one for each tag. Not applicable for tags which already exist on the server.

Returns:
httplib.HTTPResponse

Raises:

ligo.gracedb.exceptions.HTTPError: if the response has a status
code >= 400.

Example:
>>> g = GraceDb()
>>> r = g.writeLog('T101383', 'Good stuff.', '/path/to/plot.png',
... tag_name='analyst_comments')
>>> print r.status
201

llama.com.gracedb.bashlines()¶: Get the lines in ~/.bashrc

llama.com.gracedb.gracedb_auth_wrapper(func)¶: A wrapper for methods connecting to GraceDb. If GRACEDB_AUTH is set to the S3 key for a LIGO robot keytab (controlled by setting environmental variable LLAMA_GRACEDB_AUTH to that key), this method will catch RunTime and ligo.gracedb.exceptions.HTTPError errors and then try to refresh authentication credentials before attempting to call the wrapped function a second time.

llama.com.gracedb.install_keytab()¶: Install the keytab, granting access to GraceDB from this device.

llama.com.gracedb.keytab()¶: Download the Kerberos keytab if it does not exist locally and return the Path to that keytab. Raises a KeyError if KEYTAB is None (due to LLAMA_GRACEDB_AUTH not being set to a LLAMA S3 key for a valid LIGO robot keytab).

llama.com.gracedb.uninstall()¶: Uninstall keytab, run kdestroy, and remove env variable declarations from .bashrc.