Refactors for documentation purposes.

Author: Frederick Ross

splunklib/binding.py

@@ -33,6 +33,7 @@
 import functools
 import logging
 from datetime import datetime
+from functools import wraps
 
 from contextlib import contextmanager
 
@@ -55,7 +56,8 @@
 DEFAULT_PORT = "8089"
 DEFAULT_SCHEME = "https"
 
-def log_duration(f):
+def _log_duration(f):
+    @wraps(f)
     def new_f(*args, **kwargs):
         start_time = datetime.now()
         val = f(*args, **kwargs)
@@ -132,7 +134,7 @@ def __add__(self, other):
     def __radd__(self, other):
         """other + self
 
-        If *other* is not a ``UrlEncoded``, URL encode it before
+        If *other* is not a ``UrlEncoded``, URL _encode it before
         adding it.
         """
         if isinstance(other, UrlEncoded):
@@ -210,7 +212,7 @@ def f():
             return 42
         print _authentication(f)
     """
-    @functools.wraps(request_fun)
+    @wraps(request_fun)
     def wrapper(self, *args, **kwargs):
         if self.token is NoAuthenticationToken:
             # Not yet logged in.
@@ -443,7 +445,7 @@ def connect(self):
         return sock
 
     @_authentication
-    @log_duration
+    @_log_duration
     def delete(self, path_segment, owner=None, app=None, sharing=None, **query):
         """DELETE at *path_segment* with the given namespace and query.
 
@@ -493,7 +495,7 @@ def delete(self, path_segment, owner=None, app=None, sharing=None, **query):
         return response
 
     @_authentication
-    @log_duration
+    @_log_duration
     def get(self, path_segment, owner=None, app=None, sharing=None, **query):
         """GET from *path_segment* with the given namespace and query.
 
@@ -543,7 +545,7 @@ def get(self, path_segment, owner=None, app=None, sharing=None, **query):
         return response
 
     @_authentication
-    @log_duration
+    @_log_duration
     def post(self, path_segment, owner=None, app=None, sharing=None, headers=[], **query):
         """POST to *path_segment* with the given namespace and query.
 
@@ -612,7 +614,7 @@ def post(self, path_segment, owner=None, app=None, sharing=None, headers=[], **q
         return response
 
     @_authentication
-    @log_duration
+    @_log_duration
     def request(self, path_segment, method="GET", headers=[], body="",
                 owner=None, app=None, sharing=None):
         """Issue an arbitrary HTTP request to *path_segment*.
@@ -868,11 +870,11 @@ def __init__(self, response):
 #   }
 #
 
-# Encode the given kwargs as a query string. This wrapper will also encode 
+# Encode the given kwargs as a query string. This wrapper will also _encode
 # a list value as a sequence of assignemnts to the corresponding arg name, 
 # for example an argument such as 'foo=[1,2,3]' will be encoded as
 # 'foo=1&foo=2&foo=3'. 
-def encode(**kwargs):
+def _encode(**kwargs):
     items = []
     for key, value in kwargs.iteritems():
         if isinstance(value, list):
@@ -882,7 +884,7 @@ def encode(**kwargs):
     return urllib.urlencode(items)
 
 # Crack the given url into (scheme, host, port, path)
-def spliturl(url):
+def _spliturl(url):
     scheme, opaque = urllib.splittype(url)
     netloc, path = urllib.splithost(opaque)
     host, port = urllib.splitport(netloc)
@@ -903,7 +905,7 @@ def delete(self, url, headers=None, **kwargs):
             # url is already a UrlEncoded. We have to manually declare
             # the query to be encoded or it will get automatically URL
             # encoded by being appended to url.
-            url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
+            url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
         message = {
             'method': "DELETE",
             'headers': headers,
@@ -916,7 +918,7 @@ def get(self, url, headers=None, **kwargs):
             # url is already a UrlEncoded. We have to manually declare
             # the query to be encoded or it will get automatically URL
             # encoded by being appended to url.
-            url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
+            url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
         return self.request(url, { 'method': "GET", 'headers': headers })
 
     def post(self, url, headers=None, **kwargs):
@@ -927,9 +929,9 @@ def post(self, url, headers=None, **kwargs):
         if 'body' in kwargs:
             body = kwargs.pop('body')
             if len(kwargs) > 0:
-                url = url + UrlEncoded('?' + encode(**kwargs), skip_encode=True)
+                url = url + UrlEncoded('?' + _encode(**kwargs), skip_encode=True)
         else:
-            body = encode(**kwargs)
+            body = _encode(**kwargs)
         message = {
             'method': "POST",
             'headers': headers,
@@ -1015,7 +1017,7 @@ def connect(scheme, host, port):
         raise ValueError("unsupported scheme: %s" % scheme)
 
     def request(url, message, **kwargs):
-        scheme, host, port, path = spliturl(url)
+        scheme, host, port, path = _spliturl(url)
         body = message.get("body", "")
         head = { 
             "Content-Length": str(len(body)),

splunklib/client.py

@@ -141,13 +141,13 @@ class OperationFailedException(Exception):
 class NoSuchCapability(Exception):
     pass
 
-def trailing(template, *targets):
+def _trailing(template, *targets):
     """Substring of *template* following all *targets*.
 
     Most easily explained by example::
 
         template = "this is a test of the bunnies."
-        trailing(template, "is", "est", "the") == \
+        _trailing(template, "is", "est", "the") == \
             " bunnies"
 
     Each target is matched successively in the string, and the string
@@ -1079,9 +1079,9 @@ def _entity_path(self, state):
         # entities' endpoints from its own properties/ to configs/.
         raw_path = urllib.unquote(state.links.alternate)
         if 'servicesNS/' in raw_path:
-            return trailing(raw_path, 'servicesNS/', '/', '/')
+            return _trailing(raw_path, 'servicesNS/', '/', '/')
         elif 'services/' in raw_path:
-            return trailing(raw_path, 'services/')
+            return _trailing(raw_path, 'services/')
         else:
             return raw_path
 

splunklib/data.py

@@ -256,7 +256,7 @@ def __getitem__(self, key):
 
 
 def record(value=None): 
-    """Returns a **record** instance constructed with an initial value that you
+    """Returns a `Record` instance constructed with an initial value that you
     provide.
     
     :param `value`: An initial record value.

splunklib/results.py

@@ -70,16 +70,16 @@ def __eq__(self, other):
     def __hash__(self):
         return hash((self.type, self.message))
 
-class ConcatenatedStream(object):
+class _ConcatenatedStream(object):
     """Lazily concatenate zero or more streams into a stream.
 
     As you read from the concatenated stream, you get characters from
-    each stream passed to ``ConcatenatedStream``, in order.
+    each stream passed to ``_ConcatenatedStream``, in order.
 
     **Example**:
 
         from StringIO import StringIO
-        s = ConcatenatedStream(StringIO("abc"), StringIO("def"))
+        s = _ConcatenatedStream(StringIO("abc"), StringIO("def"))
         assert s.read() == "abcdef"
     """
     def __init__(self, *streams):
@@ -100,7 +100,7 @@ def read(self, n=None):
                 del self.streams[0]
         return response
 
-class XMLDTDFilter(object):
+class _XMLDTDFilter(object):
     """Lazily remove all XML DTDs from a stream.
 
     All substrings matching the regular expression <?[^>]*> are
@@ -110,7 +110,7 @@ class XMLDTDFilter(object):
     **Example**::
 
         from StringIO import StringIO
-        s = XMLDTDFilter("<?xml abcd><element><?xml ...></element>")
+        s = _XMLDTDFilter("<?xml abcd><element><?xml ...></element>")
         assert s.read() == "<element></element>"
     """
     def __init__(self, stream):
@@ -173,7 +173,7 @@ class ResultsReader(object):
     # client.Job.results_preview and client.Job.results to match any
     # changes made to ResultsReader.
     #
-    # This wouldn't be a class, just the parse_results function below,
+    # This wouldn't be a class, just the _parse_results function below,
     # except that you cannot get the current generator inside the
     # function creating that generator. Thus it's all wrapped up for
     # the sake of one field.
@@ -187,18 +187,19 @@ def __init__(self, stream):
         # destroy the stream and throw an error. To get around this,
         # we remove all the DTD definitions inline, then wrap the
         # fragments in a fiction <doc> element to make the parser happy.
-        stream = XMLDTDFilter(stream)
-        stream = ConcatenatedStream(StringIO("<doc>"), stream, StringIO("</doc>"))
+        stream = _XMLDTDFilter(stream)
+        stream = _ConcatenatedStream(StringIO("<doc>"), stream, StringIO("</doc>"))
         self.is_preview = None
-        self._gen = self.parse_results(stream)
+        self._gen = self._parse_results(stream)
 
     def __iter__(self):
         return self
 
     def next(self):
         return self._gen.next()
 
-    def parse_results(self, stream):
+    def _parse_results(self, stream):
+        """Parse results and messages out of *stream*."""
         result = None
         values = None
         try:

tests/test_job.py

@@ -22,7 +22,7 @@
 import splunklib.client as client
 import splunklib.results as results
 
-from splunklib.binding import log_duration
+from splunklib.binding import _log_duration
 
 class TestUtilities(testlib.SDKTestCase):
     def test_service_search(self):
@@ -165,7 +165,7 @@ def tearDown(self):
         super(TestJob, self).tearDown()
         self.job.cancel()
 
-    @log_duration
+    @_log_duration
     def test_get_preview_and_events(self):
         self.assertEventuallyTrue(self.job.is_done)
         self.assertLessEqual(int(self.job['eventCount']), 3)
@@ -280,12 +280,12 @@ def test_results_reader_with_streaming_results(self):
 
     def test_xmldtd_filter(self):
         from StringIO import StringIO
-        s = results.XMLDTDFilter(StringIO("<?xml asdf awe awdf=""><boris>Other stuf</boris><?xml dafawe \n asdfaw > ab"))
+        s = results._XMLDTDFilter(StringIO("<?xml asdf awe awdf=""><boris>Other stuf</boris><?xml dafawe \n asdfaw > ab"))
         self.assertEqual(s.read(), "<boris>Other stuf</boris> ab")
 
     def test_concatenated_stream(self):
         from StringIO import StringIO
-        s = results.ConcatenatedStream(StringIO("This is a test "), 
+        s = results._ConcatenatedStream(StringIO("This is a test "),
                                        StringIO("of the emergency broadcast system."))
         self.assertEqual(s.read(3), "Thi")
         self.assertEqual(s.read(20), 's is a test of the e')

tests/test_service.py

@@ -138,19 +138,19 @@ class TestTrailing(unittest.TestCase):
     template = '/servicesNS/boris/search/another/path/segment/that runs on'
 
     def test_raises_when_not_found_first(self):
-        self.assertRaises(ValueError, client.trailing, 'this is a test', 'boris')
+        self.assertRaises(ValueError, client._trailing, 'this is a test', 'boris')
 
     def test_raises_when_not_found_second(self):
-        self.assertRaises(ValueError, client.trailing, 'this is a test', 's is', 'boris')
+        self.assertRaises(ValueError, client._trailing, 'this is a test', 's is', 'boris')
 
     def test_no_args_is_identity(self):
-        self.assertEqual(self.template, client.trailing(self.template))
+        self.assertEqual(self.template, client._trailing(self.template))
 
     def test_trailing_with_one_arg_works(self):
-        self.assertEqual('boris/search/another/path/segment/that runs on', client.trailing(self.template, 'ervicesNS/'))
+        self.assertEqual('boris/search/another/path/segment/that runs on', client._trailing(self.template, 'ervicesNS/'))
 
     def test_trailing_with_n_args_works(self):
-        self.assertEqual('another/path/segment/that runs on', client.trailing(self.template, 'servicesNS/', '/', '/'))
+        self.assertEqual('another/path/segment/that runs on', client._trailing(self.template, 'servicesNS/', '/', '/'))
 
 
 if __name__ == "__main__":