gracedb-sdk Documentation¶
gracedb-sdk is a REST API client for the LIGO/Virgo Gravitational-Wave Candidate Event Database (GraceDB). It uses the powerful Requests package for reliable and high-throughput HTTP connection pooling.
API¶
-
class
gracedb_sdk.
Client
(url='https://gracedb.ligo.org/api/', *args, **kwargs)[source]¶ Bases:
gracedb_sdk.api.API
GraceDB client session.
Parameters: - url (str) – GraceDB Client URL.
- cert (str, tuple) – Client-side X.509 certificate. May be either a single filename if the certificate and private key are concatenated together, or a tuple of the filenames for the certificate and private key.
- username (str) – Username for basic auth.
- password (str) – Password for basic auth.
- force_noauth (bool, default=False) – If true, then do not use any authentication at all.
- fail_if_noauth (bool, default=False) – If true, then raise an exception if authentication credentials are not provided.
- cert_reload (bool, default=False) – If true, then automatically reload the client certificate before it expires.
- cert_cert_reload_timeout (int, default=300) – Reload the certificate this many seconds before it expires.
Notes
When a new Client instance is created, the following sources of authentication are tried, in order:
- If the
force_noauth
keyword argument is true, then perform no authentication at all. - If the
cert
keyword argument is provided, then use X.509 client certificate authentication. - If the
username
andpassword
keyword arguments are provided, then use basic auth. - Look for a default X.509 client certificate in:
- the environment variables
X509_USER_CERT
andX509_USER_KEY
- the environment variable
X509_USER_PROXY
- the file
/tmp/x509up_uUID
, whereUID
is your numeric user ID - the files
~/.globus/usercert.pem
and~/.globus/userkey.pem
- the environment variables
- Read the netrc file [1] located at
~/.netrc
, or at the path stored in the environment variableNETRC
, and look for a username and password matching the hostname in the URL. - If the
fail_if_noauth
keyword argument is true, and no authentication source was found, then raise aValueError
.
The following methods are supported for events:
client.events.get()
client.events.search(query=query, sort=sort)
client.events.create(filename=filename, filecontents=filecontents, group=group, pipeline=pipeline, search=search, labels=labels, offline=offline)
client.events.update(event_id, filename=filename, filecontents=filecontents)
client.events[event_id].get()
client.events[event_id].files.get()
client.events[event_id].files[filename].get()
client.events[event_id].labels.get()
client.events[event_id].labels.create(label)
client.events[event_id].labels.delete(label)
client.events[event_id].logs.get()
client.events[event_id].logs.create(comment=comment, filename=filename, filecontents=filecontents, tags=tags)
client.events[event_id].logs[N].tags.create(tag)
client.events[event_id].logs[N].tags.delete(tag)
client.events[event_id].voevents.get()
client.events[event_id].voevents.create(voevent_type={}, internal=internal, open_alert=open_alert, hardware_inj=hardware_inj, skymap_type=skymap_type, skymap_filename=skymap_filename, ProbHasNS=ProbHasNS, ProbHasRemnant=ProbHasRemnant, BNS=BNS, NSBH=NSBH, BBH=BBH, Terrestrial=Terrestrial, MassGap=MassGap, coinc_comment=coinc_comment)
Analogous methods are supported for superevents:
client.superevents.get()
client.superevents.search(query=query, sort=sort)
client.superevents.create(t_start=t_start, t_0=t_0, t_end=t_end, preferred_event=preferred_event, events=events, labels=labels)
client.superevents.update(superevent_id, t_start=t_start, t_0=t_0, t_end=t_end, preferred_event=preferred_event)
client.superevents[superevent_id].add(event_id)
client.superevents[superevent_id].remove(event_id)
client.superevents[superevent_id].is_exposed()
client.superevents[superevent_id].expose()
client.superevents[superevent_id].unexpose()
client.superevents[superevent_id].signoff(‘ADV’|’H1’|’L1’|’V1’, ‘OK’|’NO’, comment)
client.superevents[superevent_id].get()
client.superevents[superevent_id].files.get()
client.superevents[superevent_id].files[filename].get()
client.superevents[superevent_id].labels.get()
client.superevents[superevent_id].labels.create(label)
client.superevents[superevent_id].labels.delete(label)
client.superevents[superevent_id].logs.get()
client.superevents[superevent_id].logs.create(comment=comment, filename=filename, filecontents=filecontents, tags=tags)
client.superevents[superevent_id].logs[N].tags.create(tag)
client.superevents[superevent_id].logs[N].tags.delete(tag)
client.superevents[superevent_id].voevents.get()
client.superevents[superevent_id].voevents.create(voevent_type={}, internal=internal, open_alert=open_alert, hardware_inj=hardware_inj, skymap_type=skymap_type, skymap_filename=skymap_filename, ProbHasNS=ProbHasNS, ProbHasRemnant=ProbHasRemnant, BNS=BNS, NSBH=NSBH, BBH=BBH, Terrestrial=Terrestrial, MassGap=MassGap, coinc_comment=coinc_comment)
References
[1] The .netrc file. https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html