26
26
# Entity state, are written so that they may be used in a fluent style.
27
27
#
28
28
29
- """Client interface to the Splunk REST API."""
29
+ """Client interface for the Splunk REST API."""
30
30
31
31
# UNDONE: Add Collection.refresh and list caching
32
32
# UNDONE: Resolve conflict between Collection.delete and name of REST method
@@ -121,12 +121,46 @@ def _parse_atom_entry(entry):
121
121
122
122
# kwargs: scheme, host, port, app, owner, username, password
123
123
def connect (** kwargs ):
124
- """Establishes an authenticated connection to the specified service."""
124
+ """Establishes an authenticated connection to a Splunk :class:`Service`.
125
+
126
+ :param `host`: host name (default `localhost`)
127
+ :param `port`: port number (default 8089)
128
+ :param `scheme`: scheme for accessing service (default `https`)
129
+ :param `owner`: owner namespace (optional)
130
+ :param `app`: app context (optional)
131
+ :param `token`: session token (optional) - enables sharing session tokens
132
+ between multiple :class:`Service` istances
133
+ :param `username`: username to login with
134
+ :param `password`: password to login with
135
+ :return: An initialized :class:`Service` instance
136
+ """
125
137
return Service (** kwargs ).login ()
126
138
127
139
class Service (Context ):
128
- """The Splunk service."""
140
+ """Representation of a Splunk service at a given address (`host:port`)
141
+ accessed using a given protocol "scheme" (`http` or `https`).
142
+
143
+ A service instance also captures an optional namespace context consisting
144
+ of an optional owner name (or "-" wildcard) and optional app name (or "-"
145
+ wildcard. In order to access :class:`Service` members the instance must
146
+ be authenticated by presenting credentials using the :meth:`login` method
147
+ or by constructing the instance using the :func:`connect` function which
148
+ both creates and authenticates the instance.
149
+ """
150
+
129
151
def __init__ (self , ** kwargs ):
152
+ """Constructs a new :class:`Service` instance using the given
153
+ arguments.
154
+
155
+ :param `host`: host name (default `localhost`)
156
+ :param `port`: port number (default 8089)
157
+ :param `scheme`: scheme for accessing service (default `https`)
158
+ :param `owner`: owner namespace (optional)
159
+ :param `app`: app context (optional)
160
+ :param `token`: session token (optional)
161
+ :param `username`: username to login with
162
+ :param `password`: password to login with
163
+ """
130
164
Context .__init__ (self , ** kwargs )
131
165
132
166
@property
@@ -136,21 +170,24 @@ def apps(self):
136
170
137
171
@property
138
172
def confs (self ):
139
- """Return a collection of configs ."""
173
+ """Return a collection of configurations ."""
140
174
return Confs (self )
141
175
142
176
@property
143
177
def capabilities (self ):
144
- """Returns a list of all Splunk capabilities."""
178
+ """Returns a list of system capabilities."""
145
179
response = self .get (PATH_CAPABILITIES )
146
180
return _load_atom (response , MATCH_ENTRY_CONTENT ).capabilities
147
181
148
182
@property
149
183
def event_types (self ):
184
+ """Returns a collection of saved event types."""
150
185
return Collection (self , PATH_EVENT_TYPES )
151
186
152
187
@property
153
188
def fired_alerts (self ):
189
+ """Returns a collection of alerts that have been fired by the service.
190
+ """
154
191
return Collection (self , PATH_FIRED_ALERTS , item = AlertGroup )
155
192
156
193
@property
@@ -160,12 +197,13 @@ def indexes(self):
160
197
161
198
@property
162
199
def info (self ):
163
- """Returns server information."""
200
+ """Returns information about the sevice ."""
164
201
response = self .get ("server/info" )
165
202
return _filter_content (_load_atom (response , MATCH_ENTRY_CONTENT ))
166
203
167
204
@property
168
205
def inputs (self ):
206
+ """Returns a collection of configured inputs."""
169
207
return Inputs (self )
170
208
171
209
@property
@@ -175,7 +213,8 @@ def jobs(self):
175
213
176
214
@property
177
215
def loggers (self ):
178
- """Returns a collection of logging categories."""
216
+ """Returns a collection of service logging categories and their status.
217
+ """
179
218
return Collection (self , PATH_LOGGER )
180
219
181
220
@property
@@ -185,28 +224,39 @@ def messages(self):
185
224
186
225
# kwargs: enable_lookups, reload_macros, parse_only, output_mode
187
226
def parse (self , query , ** kwargs ):
188
- """Test a search query through the parser."""
227
+ """Parse the given search query and return a semantic map of the search.
228
+
229
+ :param query: the search query to parse
230
+ :param kwargs: optional arguments to pass to the `search/parser`
231
+ endpoint
232
+ :return: semantic map of the parsed search query
233
+ """
189
234
return self .get ("search/parser" , q = query , ** kwargs )
190
235
191
236
def restart (self ):
192
- """Restart the service."""
237
+ """Restart the service. The service will be unavailable until it has
238
+ successfully restarted.
239
+ """
193
240
return self .get ("server/control/restart" )
194
241
195
242
@property
196
243
def roles (self ):
244
+ """Returns a collection of user roles."""
197
245
return Collection (self , PATH_ROLES )
198
246
199
247
@property
200
248
def saved_searches (self ):
249
+ """Returns a collection of saved searches."""
201
250
return SavedSearches (self )
202
251
203
252
@property
204
253
def settings (self ):
205
- """Return the server settings entity ."""
254
+ """Returns configuration settings for the service ."""
206
255
return Settings (self )
207
256
208
257
@property
209
258
def users (self ):
259
+ """Returns a collection of users."""
210
260
return Users (self )
211
261
212
262
class Endpoint (object ):
0 commit comments