Skip to content

Commit fca24c1

Browse files
committed
First set of elements added to index.rst and first pass on updating :class:Service docstrings.
1 parent af2a2b8 commit fca24c1

File tree

2 files changed

+62
-10
lines changed

2 files changed

+62
-10
lines changed

docs/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Contents:
88

99
.. automodule:: splunklib.client
1010

11+
.. autofunction:: connect
12+
1113
.. autoclass:: Collection
1214
:members:
1315

splunklib/client.py

Lines changed: 60 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
# Entity state, are written so that they may be used in a fluent style.
2727
#
2828

29-
"""Client interface to the Splunk REST API."""
29+
"""Client interface for the Splunk REST API."""
3030

3131
# UNDONE: Add Collection.refresh and list caching
3232
# UNDONE: Resolve conflict between Collection.delete and name of REST method
@@ -121,12 +121,46 @@ def _parse_atom_entry(entry):
121121

122122
# kwargs: scheme, host, port, app, owner, username, password
123123
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+
"""
125137
return Service(**kwargs).login()
126138

127139
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+
129151
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+
"""
130164
Context.__init__(self, **kwargs)
131165

132166
@property
@@ -136,21 +170,24 @@ def apps(self):
136170

137171
@property
138172
def confs(self):
139-
"""Return a collection of configs."""
173+
"""Return a collection of configurations."""
140174
return Confs(self)
141175

142176
@property
143177
def capabilities(self):
144-
"""Returns a list of all Splunk capabilities."""
178+
"""Returns a list of system capabilities."""
145179
response = self.get(PATH_CAPABILITIES)
146180
return _load_atom(response, MATCH_ENTRY_CONTENT).capabilities
147181

148182
@property
149183
def event_types(self):
184+
"""Returns a collection of saved event types."""
150185
return Collection(self, PATH_EVENT_TYPES)
151186

152187
@property
153188
def fired_alerts(self):
189+
"""Returns a collection of alerts that have been fired by the service.
190+
"""
154191
return Collection(self, PATH_FIRED_ALERTS, item=AlertGroup)
155192

156193
@property
@@ -160,12 +197,13 @@ def indexes(self):
160197

161198
@property
162199
def info(self):
163-
"""Returns server information."""
200+
"""Returns information about the sevice."""
164201
response = self.get("server/info")
165202
return _filter_content(_load_atom(response, MATCH_ENTRY_CONTENT))
166203

167204
@property
168205
def inputs(self):
206+
"""Returns a collection of configured inputs."""
169207
return Inputs(self)
170208

171209
@property
@@ -175,7 +213,8 @@ def jobs(self):
175213

176214
@property
177215
def loggers(self):
178-
"""Returns a collection of logging categories."""
216+
"""Returns a collection of service logging categories and their status.
217+
"""
179218
return Collection(self, PATH_LOGGER)
180219

181220
@property
@@ -185,28 +224,39 @@ def messages(self):
185224

186225
# kwargs: enable_lookups, reload_macros, parse_only, output_mode
187226
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+
"""
189234
return self.get("search/parser", q=query, **kwargs)
190235

191236
def restart(self):
192-
"""Restart the service."""
237+
"""Restart the service. The service will be unavailable until it has
238+
successfully restarted.
239+
"""
193240
return self.get("server/control/restart")
194241

195242
@property
196243
def roles(self):
244+
"""Returns a collection of user roles."""
197245
return Collection(self, PATH_ROLES)
198246

199247
@property
200248
def saved_searches(self):
249+
"""Returns a collection of saved searches."""
201250
return SavedSearches(self)
202251

203252
@property
204253
def settings(self):
205-
"""Return the server settings entity."""
254+
"""Returns configuration settings for the service."""
206255
return Settings(self)
207256

208257
@property
209258
def users(self):
259+
"""Returns a collection of users."""
210260
return Users(self)
211261

212262
class Endpoint(object):

0 commit comments

Comments
 (0)