Skip to content

Commit 198be54

Browse files
committed
Edited doc strings
Edited all of the doc strings for beta.
1 parent 2038fc9 commit 198be54

File tree

4 files changed

+309
-250
lines changed

4 files changed

+309
-250
lines changed

splunklib/binding.py

Lines changed: 84 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,16 @@
1212
# License for the specific language governing permissions and limitations
1313
# under the License.
1414

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>`_.
1617
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
1920
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.
2325
"""
2426

2527
#
@@ -71,12 +73,13 @@
7173
DEFAULT_SCHEME = "https"
7274

7375
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.
7578
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.
8083
"""
8184
scheme = kwargs.get("scheme", DEFAULT_SCHEME)
8285
host = kwargs.get("host", DEFAULT_HOST)
@@ -86,12 +89,13 @@ def prefix(**kwargs):
8689

8790
# kwargs: sharing, owner, app
8891
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.
9194
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).
9599
"""
96100
sharing = kwargs.get('sharing', None)
97101
if sharing in ["system"]:
@@ -112,25 +116,29 @@ def namespace(**kwargs):
112116
raise ValueError("Invalid value for argument: 'sharing'")
113117

114118
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.
117121
118-
A context also captures optional namespace context consisting of an
122+
A context also captures an optional namespace context consisting of an
119123
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
121125
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).
134142
"""
135143
def __init__(self, handler=None, **kwargs):
136144
self.http = HttpLib(handler)
@@ -153,34 +161,34 @@ def connect(self):
153161
return ssl.wrap_socket(cn) if self.scheme == "https" else cn
154162

155163
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.
157165
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).
160168
"""
161169
return self.http.delete(self.url(path), self._headers(), **kwargs)
162170

163171
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.
165173
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).
168176
"""
169177
return self.http.get(self.url(path), self._headers(), **kwargs)
170178

171179
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.
173181
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).
176184
"""
177185
return self.http.post(self.url(path), self._headers(), **kwargs)
178186

179187
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.
181189
182-
:param `path`: resource path
183-
:param `request`: request message
190+
:param `path`: The resource path (REST endpoint).
191+
:param `request`: The request message.
184192
"""
185193
return self.http.request(
186194
self.url(path), {
@@ -189,8 +197,8 @@ def request(self, path, message):
189197
'body': message.get("body", "")})
190198

191199
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.
194202
"""
195203
response = self.http.post(
196204
self.url("/services/auth/login"),
@@ -202,18 +210,18 @@ def login(self):
202210
return self
203211

204212
def logout(self):
205-
"""Forget the current session token."""
213+
"""Forgets the current session token."""
206214
self.token = None
207215
return self
208216

209217
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.
213221
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).
217225
"""
218226
if path.startswith('/'):
219227
return path
@@ -234,30 +242,35 @@ def fullpath(self, path, **kwargs):
234242
aname = "-" if ns.app is None else ns.app
235243
return "/servicesNS/%s/%s/%s" % (oname, aname, path)
236244

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
238246
# the given path with namespace segments if necessarry and then prefixing
239247
# with the scheme, host and port.
240248
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.
242251
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.
244254
"""
245255
return self.prefix + self.fullpath(path)
246256

247257
# kwargs: scheme, host, port, app, owner, username, password
248258
def connect(**kwargs):
249259
"""Establishes an authenticated context with the host.
250260
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.
261274
"""
262275
return Context(**kwargs).login()
263276

@@ -269,7 +282,7 @@ def read_error_message(response):
269282
return body, XML(body).findtext("./messages/msg")
270283

271284
class HTTPError(Exception):
272-
"""Raised for HTTP responses that return an error."""
285+
"""This class is raised for HTTP responses that return an error."""
273286
def __init__(self, response):
274287
status = response.status
275288
reason = response.reason
@@ -381,11 +394,11 @@ def read(self, size = None):
381394

382395
def handler(key_file=None, cert_file=None, timeout=None):
383396
"""Returns an instance of the default HTTP request handler that uses
384-
the given argument values.
397+
the argument values you provide.
385398
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).
389402
"""
390403

391404
def connect(scheme, host, port):

0 commit comments

Comments
 (0)