1# 

2# Copyright (C) 2019-2020 Leo P. Singer <leo.singer@ligo.org> 

3# 

4# This program is free software: you can redistribute it and/or modify 

5# it under the terms of the GNU General Public License as published by 

6# the Free Software Foundation, either version 3 of the License, or 

7# (at your option) any later version. 

8# 

9# This program is distributed in the hope that it will be useful, 

10# but WITHOUT ANY WARRANTY; without even the implied warranty of 

11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

12# GNU General Public License for more details. 

13# 

14# You should have received a copy of the GNU General Public License 

15# along with this program. If not, see <https://www.gnu.org/licenses/>. 

16# 

17from requests_gracedb import Session 

18 

19from .api import API 

20 

21from ._version import get_versions 

22__version__ = get_versions()['version'] 

23del get_versions 

24 

25__all__ = ('Client',) 

26 

27 

28class Client(API): 

29 """GraceDB client session. 

30 

31 Parameters 

32 ---------- 

33 url : str 

34 GraceDB Client URL. 

35 cert : str, tuple 

36 Client-side X.509 certificate. May be either a single filename 

37 if the certificate and private key are concatenated together, or 

38 a tuple of the filenames for the certificate and private key. 

39 username : str 

40 Username for basic auth. 

41 password : str 

42 Password for basic auth. 

43 force_noauth : bool, default=False 

44 If true, then do not use any authentication at all. 

45 fail_if_noauth : bool, default=False 

46 If true, then raise an exception if authentication credentials are 

47 not provided. 

48 cert_reload : bool, default=False 

49 If true, then automatically reload the client certificate before it 

50 expires. 

51 cert_cert_reload_timeout : int, default=300 

52 Reload the certificate this many seconds before it expires. 

53 

54 Notes 

55 ----- 

56 When a new Client instance is created, the following sources of 

57 authentication are tried, in order: 

58 

59 1. If the :obj:`force_noauth` keyword argument is true, then perform no 

60 authentication at all. 

61 

62 2. If the :obj:`cert` keyword argument is provided, then use X.509 client 

63 certificate authentication. 

64 

65 3. If the :obj:`username` and :obj:`password` keyword arguments are 

66 provided, then use basic auth. 

67 

68 4. Look for a default X.509 client certificate in: 

69 

70 a. the environment variables :envvar:`X509_USER_CERT` and 

71 :envvar:`X509_USER_KEY` 

72 b. the environment variable :envvar:`X509_USER_PROXY` 

73 c. the file :file:`/tmp/x509up_u{UID}`, where :samp:`{UID}` is your 

74 numeric user ID 

75 d. the files :file:`~/.globus/usercert.pem` and 

76 :file:`~/.globus/userkey.pem` 

77 

78 5. Read the netrc file [1]_ located at :file:`~/.netrc`, or at the path stored 

79 in the environment variable :envvar:`NETRC`, and look for a username 

80 and password matching the hostname in the URL. 

81 

82 6. If the :obj:`fail_if_noauth` keyword argument is true, and no 

83 authentication source was found, then raise a :class:`ValueError`. 

84 

85 The following methods are supported for events: 

86 

87 * :samp:`client.events.get()` 

88 * :samp:`client.events.search(query={query}, sort={sort})` 

89 * :samp:`client.events.create(filename={filename}, filecontents={filecontents}, group={group}, pipeline={pipeline}, search={search}, labels={labels}, offline={offline})` 

90 * :samp:`client.events.update({event_id}, filename={filename}, filecontents={filecontents})` 

91 * :samp:`client.events[{event_id}].get()` 

92 * :samp:`client.events[{event_id}].files.get()` 

93 * :samp:`client.events[{event_id}].files[{filename}].get()` 

94 * :samp:`client.events[{event_id}].labels.get()` 

95 * :samp:`client.events[{event_id}].labels.create({label})` 

96 * :samp:`client.events[{event_id}].labels.delete({label})` 

97 * :samp:`client.events[{event_id}].logs.get()` 

98 * :samp:`client.events[{event_id}].logs.create(comment={comment}, filename={filename}, filecontents={filecontents}, tags={tags})` 

99 * :samp:`client.events[{event_id}].logs[{N}].tags.create({tag})` 

100 * :samp:`client.events[{event_id}].logs[{N}].tags.delete({tag})` 

101 * :samp:`client.events[{event_id}].voevents.get()` 

102 * :samp:`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})` 

103 

104 Analogous methods are supported for superevents: 

105 

106 * :samp:`client.superevents.get()` 

107 * :samp:`client.superevents.search(query={query}, sort={sort})` 

108 * :samp:`client.superevents.create(t_start={t_start}, t_0={t_0}, t_end={t_end}, preferred_event={preferred_event}, events={events}, labels={labels})` 

109 * :samp:`client.superevents.update({superevent_id}, t_start={t_start}, t_0={t_0}, t_end={t_end}, preferred_event={preferred_event})` 

110 * :samp:`client.superevents[{superevent_id}].add({event_id})` 

111 * :samp:`client.superevents[{superevent_id}].remove({event_id})` 

112 * :samp:`client.superevents[{superevent_id}].is_exposed()` 

113 * :samp:`client.superevents[{superevent_id}].expose()` 

114 * :samp:`client.superevents[{superevent_id}].unexpose()` 

115 * :samp:`client.superevents[{superevent_id}].signoff({'ADV'|'H1'|'L1'|'V1'}, {'OK'|'NO'}, {comment})` 

116 * :samp:`client.superevents[{superevent_id}].get()` 

117 * :samp:`client.superevents[{superevent_id}].files.get()` 

118 * :samp:`client.superevents[{superevent_id}].files[{filename}].get()` 

119 * :samp:`client.superevents[{superevent_id}].labels.get()` 

120 * :samp:`client.superevents[{superevent_id}].labels.create({label})` 

121 * :samp:`client.superevents[{superevent_id}].labels.delete({label})` 

122 * :samp:`client.superevents[{superevent_id}].logs.get()` 

123 * :samp:`client.superevents[{superevent_id}].logs.create(comment={comment}, filename={filename}, filecontents={filecontents}, tags={tags})` 

124 * :samp:`client.superevents[{superevent_id}].logs[{N}].tags.create({tag})` 

125 * :samp:`client.superevents[{superevent_id}].logs[{N}].tags.delete({tag})` 

126 * :samp:`client.superevents[{superevent_id}].voevents.get()` 

127 * :samp:`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})` 

128 

129 References 

130 ---------- 

131 .. [1] The .netrc file. 

132 https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html 

133 

134 """ # noqa: E501 

135 

136 def __init__(self, url='https://gracedb.ligo.org/api/', *args, **kwargs): 

137 super().__init__(url, Session(url=url, *args, **kwargs)) 

138 

139 def close(self): 

140 self.session.close() 

141 

142 def __enter__(self): 

143 return self 

144 

145 def __exit__(self, *args): 

146 self.close()