12
12
# License for the specific language governing permissions and limitations
13
13
# under the License.
14
14
15
- """Low-level *binding* interface for the Splunk REST API.
15
+ """This module contains a low-level *binding* interface to the `Splunk REST API
16
+ <http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTcontents>`_.
16
17
17
- This module is designed to enable client side interaction with the Splunk
18
- REST API at the level of HTTP requests and responses and provides some simple
18
+ This module is designed to enable client- side interaction with the Splunk
19
+ REST API at the level of HTTP requests and responses, and it provides simple
19
20
helpers for things like Splunk authentication and the use of Splunk namespaces.
20
- This module is specifically designed to be *lightweight* and faithful to the
21
- underlying REST API. If you are looking for a *friendlier* interface to the
22
- Splunk REST API then you should consider the :mod:splunklib.client module.
21
+
22
+ This module is specifically designed to be lightweight and faithful to the
23
+ underlying Splunk REST API. If you want a friendlier interface to the Splunk
24
+ REST API, consider using the :mod:`splunklib.client` module.
23
25
"""
24
26
25
27
#
71
73
DEFAULT_SCHEME = "https"
72
74
73
75
def prefix (** kwargs ):
74
- """Returns an URL prefix constructed from the given arguments.
76
+ """Returns a URL prefix (such as *https://localhost:8089*) that is
77
+ constructed from the arguments you provide.
75
78
76
- :param `scheme`: URL scheme (http or https)
77
- :param `host`: host name
78
- :param `port`: prot number
79
- :return: URL prefix, for example https://localhost:8089
79
+ :param `scheme`: The URL scheme (* http* or * https*).
80
+ :param `host`: The host name.
81
+ :param `port`: The port number.
82
+ :return: The URL prefix.
80
83
"""
81
84
scheme = kwargs .get ("scheme" , DEFAULT_SCHEME )
82
85
host = kwargs .get ("host" , DEFAULT_HOST )
@@ -86,12 +89,13 @@ def prefix(**kwargs):
86
89
87
90
# kwargs: sharing, owner, app
88
91
def namespace (** kwargs ):
89
- """Returns a reconciled dict of namespace values built from the given
90
- arguments.
92
+ """Returns a reconciled dictionary of namespace values built from the
93
+ arguments you provide .
91
94
92
- :param `sharing`: sharing mode (system, global, app, user) (default user)
93
- :param `owner`: owner context (optional)
94
- :param `app`: app context (optional)
95
+ :param `sharing`: The sharing mode: *system*, *global*, *app*, or *user*
96
+ (the default is *user*).
97
+ :param `owner`: The owner context (optional).
98
+ :param `app`: The app context (optional).
95
99
"""
96
100
sharing = kwargs .get ('sharing' , None )
97
101
if sharing in ["system" ]:
@@ -112,25 +116,29 @@ def namespace(**kwargs):
112
116
raise ValueError ("Invalid value for argument: 'sharing'" )
113
117
114
118
class Context (object ):
115
- """A binding context to a corresponding Splunk service that can be used to
116
- issue HTTP requests.
119
+ """This class provides a binding context to a corresponding Splunk service
120
+ that can be used to issue HTTP requests.
117
121
118
- A context also captures optional namespace context consisting of an
122
+ A context also captures an optional namespace context consisting of an
119
123
optional owner name (or "-" wildcard) and optional app name (or "-"
120
- wildcard. In order to use the :class:`Context` it instance must be
124
+ wildcard). To use the :class:`Context` class, the instance must be
121
125
authenticated by presenting credentials using the :meth:`login` method
122
- or by constructing the instance using the :func:`connect` function
123
- which both creates and authenticates the instance.
124
-
125
- :param `host`: host name (default `localhost`)
126
- :param `port`: port number (default 8089)
127
- :param `scheme`: scheme for accessing service (default `https`)
128
- :param `owner`: owner namespace (optional)
129
- :param `app`: app context (optional)
130
- :param `token`: session token to reuse (optional)
131
- :param `username`: username to login with
132
- :param `password`: password to login with
133
- :param `handler`: HTTP request handler (optional)
126
+ or by constructing the instance using the :func:`connect` function, which
127
+ both creates and authenticates the instance.
128
+
129
+ :param `host`: The host name (the default is *localhost*).
130
+ :param `port`: The port number (the default is *8089*).
131
+ :param `scheme`: The scheme for accessing the service (the default is
132
+ *https*).
133
+ :param `owner`: The owner namespace (optional).
134
+ :param `app`: The app context (optional).
135
+ :param `token`: The current session token (optional). Session tokens can be
136
+ shared across multiple service instances.
137
+ :param `username`: The Splunk account username, which is used to
138
+ authenticate the Splunk instance.
139
+ :param `password`: The password, which is used to authenticate the Splunk
140
+ instance.
141
+ :param `handler`: The HTTP request handler (optional).
134
142
"""
135
143
def __init__ (self , handler = None , ** kwargs ):
136
144
self .http = HttpLib (handler )
@@ -153,34 +161,34 @@ def connect(self):
153
161
return ssl .wrap_socket (cn ) if self .scheme == "https" else cn
154
162
155
163
def delete (self , path , ** kwargs ):
156
- """Issue a DELETE request to the given path .
164
+ """Issues a `` DELETE`` request to a REST endpoint you specify .
157
165
158
- :param `path`: resource path
159
- :param `kwargs`: request arguments (optional)
166
+ :param `path`: The resource path (REST endpoint).
167
+ :param `kwargs`: Request arguments (optional).
160
168
"""
161
169
return self .http .delete (self .url (path ), self ._headers (), ** kwargs )
162
170
163
171
def get (self , path , ** kwargs ):
164
- """Issue a GET request to the given path .
172
+ """Issues a `` GET`` request to a REST endpoint you specify .
165
173
166
- :param `path`: resource path
167
- :param `kwargs`: query arguments (optional)
174
+ :param `path`: The resource path (REST endpoint).
175
+ :param `kwargs`: Query arguments (optional).
168
176
"""
169
177
return self .http .get (self .url (path ), self ._headers (), ** kwargs )
170
178
171
179
def post (self , path , ** kwargs ):
172
- """Issue a POST request to the given path .
180
+ """Issues a `` POST`` request to a REST endpoint you specify .
173
181
174
- :param `path`: resource path
175
- :param `kwargs`: form arguments (optional)
182
+ :param `path`: The resource path (REST endpoint).
183
+ :param `kwargs`: Form arguments (optional).
176
184
"""
177
185
return self .http .post (self .url (path ), self ._headers (), ** kwargs )
178
186
179
187
def request (self , path , message ):
180
- """Issue the given HTTP request message to the given endpoint.
188
+ """Issues an `` HTTP`` request message to a REST endpoint you specify .
181
189
182
- :param `path`: resource path
183
- :param `request`: request message
190
+ :param `path`: The resource path (REST endpoint).
191
+ :param `request`: The request message.
184
192
"""
185
193
return self .http .request (
186
194
self .url (path ), {
@@ -189,8 +197,8 @@ def request(self, path, message):
189
197
'body' : message .get ("body" , "" )})
190
198
191
199
def login (self ):
192
- """Issue a Splunk login request using the context's credentials and
193
- store the session token for use on subsequent requests.
200
+ """Issues a Splunk login request using the context's credentials and
201
+ stores the session token for use on subsequent requests.
194
202
"""
195
203
response = self .http .post (
196
204
self .url ("/services/auth/login" ),
@@ -202,18 +210,18 @@ def login(self):
202
210
return self
203
211
204
212
def logout (self ):
205
- """Forget the current session token."""
213
+ """Forgets the current session token."""
206
214
self .token = None
207
215
return self
208
216
209
217
def fullpath (self , path , ** kwargs ):
210
- """Returns a full resource path given a potential path fragment and
211
- then completing with namespace segments using the namespace args,
212
- if provided, otherwise using the context namespace values.
218
+ """Returns a full REST endpoint using an endpoint path or path fragment,
219
+ then adds namespace segments by either using any namespace arguments
220
+ that are provided or the context namespace values.
213
221
214
- :param `path`: resource path, potentially a fragment
215
- :param `kwargs`: optional namespace arguments to use for path
216
- completion ( sharing, owner, app)
222
+ :param `path`: The resource path (REST endpoint), possibly a fragment.
223
+ :param `kwargs`: Namespace arguments to use for completing the path:
224
+ * sharing*, * owner*, and * app* (optional).
217
225
"""
218
226
if path .startswith ('/' ):
219
227
return path
@@ -234,30 +242,35 @@ def fullpath(self, path, **kwargs):
234
242
aname = "-" if ns .app is None else ns .app
235
243
return "/servicesNS/%s/%s/%s" % (oname , aname , path )
236
244
237
- # Convet the given path into a fully qualified URL by first qualifying
245
+ # Convert the given path into a fully qualified URL by first qualifying
238
246
# the given path with namespace segments if necessarry and then prefixing
239
247
# with the scheme, host and port.
240
248
def url (self , path ):
241
- """Converts the given path or path fragment into a complete URL.
249
+ """Converts a REST endpoint (from a path or path fragment) into a
250
+ complete URL.
242
251
243
- :param `path`: resource path to convert to a full URL
252
+ :param `path`: The resource path (REST endpoint) to convert to a full
253
+ URL.
244
254
"""
245
255
return self .prefix + self .fullpath (path )
246
256
247
257
# kwargs: scheme, host, port, app, owner, username, password
248
258
def connect (** kwargs ):
249
259
"""Establishes an authenticated context with the host.
250
260
251
- :param `host`: host name (default `localhost`)
252
- :param `port`: port number (default 8089)
253
- :param `scheme`: scheme for accessing service (default `https`)
254
- :param `owner`: owner namespace (optional)
255
- :param `app`: app context (optional)
256
- :param `token`: session token (optional) - enables sharing session tokens
257
- between multiple :class:`Service` istances
258
- :param `username`: username to login with
259
- :param `password`: password to login with
260
- :return: An initialized :class:`Context` instance
261
+ :param `host`: The host name (the default is *localhost*).
262
+ :param `port`: The port number (the default is *8089*).
263
+ :param `scheme`: The scheme for accessing the service (the default is
264
+ *https*).
265
+ :param `owner`: The owner namespace (optional).
266
+ :param `app`: The app context (optional).
267
+ :param `token`: The current session token (optional). Session tokens can be
268
+ shared across multiple service instances.
269
+ :param `username`: The Splunk account username, which is used to
270
+ authenticate the Splunk instance.
271
+ :param `password`: The password, which is used to authenticate the Splunk
272
+ instance.
273
+ :return: An initialized :class:`Context` instance.
261
274
"""
262
275
return Context (** kwargs ).login ()
263
276
@@ -269,7 +282,7 @@ def read_error_message(response):
269
282
return body , XML (body ).findtext ("./messages/msg" )
270
283
271
284
class HTTPError (Exception ):
272
- """Raised for HTTP responses that return an error."""
285
+ """This class is raised for HTTP responses that return an error."""
273
286
def __init__ (self , response ):
274
287
status = response .status
275
288
reason = response .reason
@@ -381,11 +394,11 @@ def read(self, size = None):
381
394
382
395
def handler (key_file = None , cert_file = None , timeout = None ):
383
396
"""Returns an instance of the default HTTP request handler that uses
384
- the given argument values.
397
+ the argument values you provide .
385
398
386
- :param `key_file`: key file (optional)
387
- :param `cert_file`: cert file (optional)
388
- :param `timeout`: request timeout (optional)
399
+ :param `key_file`: The key file (optional).
400
+ :param `cert_file`: The cert file (optional).
401
+ :param `timeout`: The request time-out period (optional).
389
402
"""
390
403
391
404
def connect (scheme , host , port ):
0 commit comments