Skip to content

Commit ba21078

Browse files
author
Frederick Ross
committed
Refactors for documentation purposes.
1 parent 083dd7e commit ba21078

6 files changed

Lines changed: 42 additions & 39 deletions

File tree

‎splunklib/binding.py‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
import functools
3434
import logging
3535
from datetime import datetime
36+
from functools import wraps
3637

3738
from contextlib import contextmanager
3839

@@ -55,7 +56,8 @@
5556
DEFAULT_PORT = "8089"
5657
DEFAULT_SCHEME = "https"
5758

58-
def log_duration(f):
59+
def _log_duration(f):
60+
@wraps(f)
5961
def new_f(*args, **kwargs):
6062
start_time = datetime.now()
6163
val = f(*args, **kwargs)
@@ -132,7 +134,7 @@ def __add__(self, other):
132134
def __radd__(self, other):
133135
"""other + self
134136
135-
If *other* is not a ``UrlEncoded``, URL encode it before
137+
If *other* is not a ``UrlEncoded``, URL _encode it before
136138
adding it.
137139
"""
138140
if isinstance(other, UrlEncoded):
@@ -210,7 +212,7 @@ def f():
210212
return 42
211213
print _authentication(f)
212214
"""
213-
@functools.wraps(request_fun)
215+
@wraps(request_fun)
214216
def wrapper(self, *args, **kwargs):
215217
if self.token is NoAuthenticationToken:
216218
# Not yet logged in.
@@ -443,7 +445,7 @@ def connect(self):
443445
return sock
444446

445447
@_authentication
446-
@log_duration
448+
@_log_duration
447449
def delete(self, path_segment, owner=None, app=None, sharing=None, **query):
448450
"""DELETE at *path_segment* with the given namespace and query.
449451
@@ -493,7 +495,7 @@ def delete(self, path_segment, owner=None, app=None, sharing=None, **query):
493495
return response
494496

495497
@_authentication
496-
@log_duration
498+
@_log_duration
497499
def get(self, path_segment, owner=None, app=None, sharing=None, **query):
498500
"""GET from *path_segment* with the given namespace and query.
499501
@@ -543,7 +545,7 @@ def get(self, path_segment, owner=None, app=None, sharing=None, **query):
543545
return response
544546

545547
@_authentication
546-
@log_duration
548+
@_log_duration
547549
def post(self, path_segment, owner=None, app=None, sharing=None, headers=[], **query):
548550
"""POST to *path_segment* with the given namespace and query.
549551
@@ -612,7 +614,7 @@ def post(self, path_segment, owner=None, app=None, sharing=None, headers=[], **q
612614
return response
613615

614616
@_authentication
615-
@log_duration
617+
@_log_duration
616618
def request(self, path_segment, method="GET", headers=[], body="",
617619
owner=None, app=None, sharing=None):
618620
"""Issue an arbitrary HTTP request to *path_segment*.
@@ -868,11 +870,11 @@ def __init__(self, response):
868870
# }
869871
#
870872

871-
# Encode the given kwargs as a query string. This wrapper will also encode
873+
# Encode the given kwargs as a query string. This wrapper will also _encode
872874
# a list value as a sequence of assignemnts to the corresponding arg name,
873875
# for example an argument such as 'foo=[1,2,3]' will be encoded as
874876
# 'foo=1&foo=2&foo=3'.
875-
def encode(**kwargs):
877+
def _encode(**kwargs):
876878
items = []
877879
for key, value in kwargs.iteritems():
878880
if isinstance(value, list):
@@ -882,7 +884,7 @@ def encode(**kwargs):
882884
return urllib.urlencode(items)
883885

884886
# Crack the given url into (scheme, host, port, path)
885-
def spliturl(url):
887+
def _spliturl(url):
886888
scheme, opaque = urllib.splittype(url)
887889
netloc, path = urllib.splithost(opaque)
888890
host, port = urllib.splitport(netloc)
@@ -903,7 +905,7 @@ def delete(self, url, headers=None, **kwargs):
903905
# url is already a UrlEncoded. We have to manually declare
904906
# the query to be encoded or it will get automatically URL
905907
# encoded by being appended to url.
906-
url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
908+
url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
907909
message = {
908910
'method': "DELETE",
909911
'headers': headers,
@@ -916,7 +918,7 @@ def get(self, url, headers=None, **kwargs):
916918
# url is already a UrlEncoded. We have to manually declare
917919
# the query to be encoded or it will get automatically URL
918920
# encoded by being appended to url.
919-
url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
921+
url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
920922
return self.request(url, { 'method': "GET", 'headers': headers })
921923

922924
def post(self, url, headers=None, **kwargs):
@@ -927,9 +929,9 @@ def post(self, url, headers=None, **kwargs):
927929
if 'body' in kwargs:
928930
body = kwargs.pop('body')
929931
if len(kwargs) > 0:
930-
url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
932+
url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
931933
else:
932-
body = encode(**kwargs)
934+
body = _encode(**kwargs)
933935
message = {
934936
'method': "POST",
935937
'headers': headers,
@@ -1015,7 +1017,7 @@ def connect(scheme, host, port):
10151017
raise ValueError("unsupported scheme: %s" % scheme)
10161018

10171019
def request(url, message, **kwargs):
1018-
scheme, host, port, path = spliturl(url)
1020+
scheme, host, port, path = _spliturl(url)
10191021
body = message.get("body", "")
10201022
head = {
10211023
"Content-Length": str(len(body)),

‎splunklib/client.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -141,13 +141,13 @@ class OperationFailedException(Exception):
141141
class NoSuchCapability(Exception):
142142
pass
143143

144-
def trailing(template, *targets):
144+
def _trailing(template, *targets):
145145
"""Substring of *template* following all *targets*.
146146
147147
Most easily explained by example::
148148
149149
template = "this is a test of the bunnies."
150-
trailing(template, "is", "est", "the") == \
150+
_trailing(template, "is", "est", "the") == \
151151
" bunnies"
152152
153153
Each target is matched successively in the string, and the string
@@ -1079,9 +1079,9 @@ def _entity_path(self, state):
10791079
# entities' endpoints from its own properties/ to configs/.
10801080
raw_path = urllib.unquote(state.links.alternate)
10811081
if 'servicesNS/' in raw_path:
1082-
return trailing(raw_path, 'servicesNS/', '/', '/')
1082+
return _trailing(raw_path, 'servicesNS/', '/', '/')
10831083
elif 'services/' in raw_path:
1084-
return trailing(raw_path, 'services/')
1084+
return _trailing(raw_path, 'services/')
10851085
else:
10861086
return raw_path
10871087

‎splunklib/data.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,7 @@ def __getitem__(self, key):
256256

257257

258258
def record(value=None):
259-
"""Returns a **record** instance constructed with an initial value that you
259+
"""Returns a `Record` instance constructed with an initial value that you
260260
provide.
261261
262262
:param `value`: An initial record value.

‎splunklib/results.py‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -70,16 +70,16 @@ def __eq__(self, other):
7070
def __hash__(self):
7171
return hash((self.type, self.message))
7272

73-
class ConcatenatedStream(object):
73+
class _ConcatenatedStream(object):
7474
"""Lazily concatenate zero or more streams into a stream.
7575
7676
As you read from the concatenated stream, you get characters from
77-
each stream passed to ``ConcatenatedStream``, in order.
77+
each stream passed to ``_ConcatenatedStream``, in order.
7878
7979
**Example**:
8080
8181
from StringIO import StringIO
82-
s = ConcatenatedStream(StringIO("abc"), StringIO("def"))
82+
s = _ConcatenatedStream(StringIO("abc"), StringIO("def"))
8383
assert s.read() == "abcdef"
8484
"""
8585
def __init__(self, *streams):
@@ -100,7 +100,7 @@ def read(self, n=None):
100100
del self.streams[0]
101101
return response
102102

103-
class XMLDTDFilter(object):
103+
class _XMLDTDFilter(object):
104104
"""Lazily remove all XML DTDs from a stream.
105105
106106
All substrings matching the regular expression <?[^>]*> are
@@ -110,7 +110,7 @@ class XMLDTDFilter(object):
110110
**Example**::
111111
112112
from StringIO import StringIO
113-
s = XMLDTDFilter("<?xml abcd><element><?xml ...></element>")
113+
s = _XMLDTDFilter("<?xml abcd><element><?xml ...></element>")
114114
assert s.read() == "<element></element>"
115115
"""
116116
def __init__(self, stream):
@@ -173,7 +173,7 @@ class ResultsReader(object):
173173
# client.Job.results_preview and client.Job.results to match any
174174
# changes made to ResultsReader.
175175
#
176-
# This wouldn't be a class, just the parse_results function below,
176+
# This wouldn't be a class, just the _parse_results function below,
177177
# except that you cannot get the current generator inside the
178178
# function creating that generator. Thus it's all wrapped up for
179179
# the sake of one field.
@@ -187,18 +187,19 @@ def __init__(self, stream):
187187
# destroy the stream and throw an error. To get around this,
188188
# we remove all the DTD definitions inline, then wrap the
189189
# fragments in a fiction <doc> element to make the parser happy.
190-
stream = XMLDTDFilter(stream)
191-
stream = ConcatenatedStream(StringIO("<doc>"), stream, StringIO("</doc>"))
190+
stream = _XMLDTDFilter(stream)
191+
stream = _ConcatenatedStream(StringIO("<doc>"), stream, StringIO("</doc>"))
192192
self.is_preview = None
193-
self._gen = self.parse_results(stream)
193+
self._gen = self._parse_results(stream)
194194

195195
def __iter__(self):
196196
return self
197197

198198
def next(self):
199199
return self._gen.next()
200200

201-
def parse_results(self, stream):
201+
def _parse_results(self, stream):
202+
"""Parse results and messages out of *stream*."""
202203
result = None
203204
values = None
204205
try:

‎tests/test_job.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
import splunklib.client as client
2323
import splunklib.results as results
2424

25-
from splunklib.binding import log_duration
25+
from splunklib.binding import _log_duration
2626

2727
class TestUtilities(testlib.SDKTestCase):
2828
def test_service_search(self):
@@ -165,7 +165,7 @@ def tearDown(self):
165165
super(TestJob, self).tearDown()
166166
self.job.cancel()
167167

168-
@log_duration
168+
@_log_duration
169169
def test_get_preview_and_events(self):
170170
self.assertEventuallyTrue(self.job.is_done)
171171
self.assertLessEqual(int(self.job['eventCount']), 3)
@@ -280,12 +280,12 @@ def test_results_reader_with_streaming_results(self):
280280

281281
def test_xmldtd_filter(self):
282282
from StringIO import StringIO
283-
s = results.XMLDTDFilter(StringIO("<?xml asdf awe awdf=""><boris>Other stuf</boris><?xml dafawe \n asdfaw > ab"))
283+
s = results._XMLDTDFilter(StringIO("<?xml asdf awe awdf=""><boris>Other stuf</boris><?xml dafawe \n asdfaw > ab"))
284284
self.assertEqual(s.read(), "<boris>Other stuf</boris> ab")
285285

286286
def test_concatenated_stream(self):
287287
from StringIO import StringIO
288-
s = results.ConcatenatedStream(StringIO("This is a test "),
288+
s = results._ConcatenatedStream(StringIO("This is a test "),
289289
StringIO("of the emergency broadcast system."))
290290
self.assertEqual(s.read(3), "Thi")
291291
self.assertEqual(s.read(20), 's is a test of the e')

‎tests/test_service.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -138,19 +138,19 @@ class TestTrailing(unittest.TestCase):
138138
template = '/servicesNS/boris/search/another/path/segment/that runs on'
139139

140140
def test_raises_when_not_found_first(self):
141-
self.assertRaises(ValueError, client.trailing, 'this is a test', 'boris')
141+
self.assertRaises(ValueError, client._trailing, 'this is a test', 'boris')
142142

143143
def test_raises_when_not_found_second(self):
144-
self.assertRaises(ValueError, client.trailing, 'this is a test', 's is', 'boris')
144+
self.assertRaises(ValueError, client._trailing, 'this is a test', 's is', 'boris')
145145

146146
def test_no_args_is_identity(self):
147-
self.assertEqual(self.template, client.trailing(self.template))
147+
self.assertEqual(self.template, client._trailing(self.template))
148148

149149
def test_trailing_with_one_arg_works(self):
150-
self.assertEqual('boris/search/another/path/segment/that runs on', client.trailing(self.template, 'ervicesNS/'))
150+
self.assertEqual('boris/search/another/path/segment/that runs on', client._trailing(self.template, 'ervicesNS/'))
151151

152152
def test_trailing_with_n_args_works(self):
153-
self.assertEqual('another/path/segment/that runs on', client.trailing(self.template, 'servicesNS/', '/', '/'))
153+
self.assertEqual('another/path/segment/that runs on', client._trailing(self.template, 'servicesNS/', '/', '/'))
154154

155155

156156
if __name__ == "__main__":

0 commit comments

Comments
 (0)