Edits to new stuff, more cleanup

apruneda · apruneda · commit 9f92cf234fc0 · 2012-11-07T18:21:50.000-08:00
I looked over Fred's additions and edited, fixed the interdoc linking.
Found more nitpicks.
diff --git a/splunklib/binding.py b/splunklib/binding.py
@@ -69,21 +69,23 @@ class AuthenticationError(Exception):
     """Raised when a login request to Splunk fails.
 
     If your username was unknown or you provided an incorrect password
-    in a call to Context.login() or Service.login(), this exception is
-    raised.
+    in a call to :meth:`Context.login` or :meth:`splunklib.client.Service.login`,
+    this exception is raised.
     """
     pass
 
 # Singleton values to eschew None
 class NoAuthenticationToken(object):
-    """The value stored in a Context or Service that is not logged in.
+    """The value stored in a :class:`Context` or :class:`splunklib.client.Service`
+    class that is not logged in.
 
-    If a Context or Service is created without an authentication token,
-    and there has not yet been a call to the login method, the token
-    field of the Context or Service is set to ``NoAuthenticationToken``.
+    If a ``Context`` or ``Service`` object is created without an authentication
+    token, and there has not yet been a call to the ``login`` method, the token
+    field of the ``Context`` or ``Service`` object is set to 
+    ``NoAuthenticationToken``.
 
-    Likewise, after a Context or Service has been logged out, the token
-    is set to this value again.
+    Likewise, after a ``Context`` or ``Service`` object has been logged out, the
+    token is set to this value again.
     """
     pass
 
@@ -936,51 +938,62 @@ def _spliturl(url):
 class HttpLib(object):
     """A set of convenient methods for making HTTP calls.
 
-    HttpLib provides a general ``request`` method, and ``delete``, ``post``,
-    and ``get`` methods for the three HTTP methods that Splunk uses.
+    ``HttpLib`` provides a general :meth:`request` method, and :meth:`delete`, 
+    :meth:`post`, and :meth:`get` methods for the three HTTP methods that Splunk
+    uses.
 
-    By default, ``HttpLib`` will use Python's built-in ``httplib`` library,
-    but you can replace it by passing your own handling function to
-    ``HttpLib``'s constructor.
+    By default, ``HttpLib`` uses Python's built-in ``httplib`` library,
+    but you can replace it by passing your own handling function to the 
+    constructor for ``HttpLib``.
 
-    The handling function should have the type::
+    The handling function should have the type:
 
-        handler(url, request_dict) -> response_dict
+        ``handler(`url`, `request_dict`) -> response_dict``
 
-    where ``url`` is the URL to make the request to (including any query and
-    fragment sections), ``request_dict`` is a dictionary with the following keys:
+    where `url` is the URL to make the request to (including any query and
+    fragment sections) as a dictionary with the following keys:
 
-    - method: the method for the request, typically ``'GET'``, ``'POST'``, or ``'DELETE'``.
-    - headers: A list of pairs specifying the HTTP headers (e.g., ``[('key': value), ...]``)
-    - body: A string giving the body to send with the request (should default to ``''``).
+        - method: The method for the request, typically ``GET``, ``POST``, or ``DELETE``.
+
+        - headers: A list of pairs specifying the HTTP headers (for example: ``[('key': value), ...]``).
+
+        - body: A string containing the body to send with the request (this string 
+          should default to '').
 
     and ``response_dict`` is a dictionary with the following keys:
 
-    - status: An integer giving the HTTP status code (e.g., 200, 404).
-    - reason: The reason phrase, if any, returned by the server
-    - headers: A list of pairs giving the response headers (e.g., ``[('key': value), ...]``)
-    - body: A stream-like object supporting ``read(size=None)`` and ``close()``
-            methods to get the body of the response.
+        - status: An integer containing the HTTP status code (such as 200 or 404).
+
+        - reason: The reason phrase, if any, returned by the server.
+
+        - headers: A list of pairs containing the response headers (for example, ``[('key': value), ...]``).
 
-    The response dictionary will be returned directly by ``HttpLib``'s methods with
-    no further processing. By default, ``HttpLib`` calls the function ``handler``
-    to get a handler function. See it for an example.
+        - body: A stream-like object supporting ``read(size=None)`` and ``close()``
+          methods to get the body of the response.
+
+    The response dictionary is returned directly by ``HttpLib``'s methods with
+    no further processing. By default, ``HttpLib`` calls the :func:`handler` function
+    to get a handler function. 
     """
     def __init__(self, custom_handler=None):
         self.handler = handler() if custom_handler is None else custom_handler
 
     def delete(self, url, headers=None, **kwargs):
-        """Send a DELETE request to *url*.
-
-        *headers* should be a list of pairs specifying the headers for
-        the HTTP response (e.g., [('Content-Type': 'text/cthulhu'), ('Token': 'boris')]).
-
-        Any additional keyword arguments are interpreted as the query
-        part of the URL. The order of keyword arguments is not preserved
-        in the request, but the keywords and their arguments will be URL
-        encoded.
-
-        :returns: A dictionary describing the response (see ``HttpLib`` for its structure).
+        """Sends a DELETE request to a URL.
+
+        :param url: The URL.
+        :type url: ``string``
+        :param headers: A list of pairs specifying the headers for the HTTP 
+            response (for example, ``[('Content-Type': 'text/cthulhu'), ('Token': 'boris')]``).
+        :type headers: ``list``
+        :param kwargs: Additional keyword arguments (optional). These arguments
+            are interpreted as the query part of the URL. The order of keyword 
+            arguments is not preserved in the request, but the keywords and 
+            their arguments will be URL encoded.
+        :type kwargs: ``dict``
+        :returns: A dictionary describing the response (see :class:`HttpLib` for
+            its structure).
+        :rtype: ``dict``
         """
         if headers is None: headers = []
         if kwargs: 
@@ -995,17 +1008,21 @@ def delete(self, url, headers=None, **kwargs):
         return self.request(url, message)
 
     def get(self, url, headers=None, **kwargs):
-        """Issue a GET request to *url*
-
-        *headers* should be a list of pairs specifying the headers for
-        the HTTP response (e.g., [('Content-Type': 'text/cthulhu'), ('Token': 'boris')]).
-
-        Any additional keyword arguments are interpreted as the query
-        part of the URL. The order of keyword arguments is not preserved
-        in the request, but the keywords and their arguments will be URL
-        encoded.
-
-        :returns: A dictionary describing the response (see ``HttpLib`` for its structure).
+        """Sends a GET request to a URL. 
+
+        :param url: The URL.
+        :type url: ``string``
+        :param headers: A list of pairs specifying the headers for the HTTP 
+            response (for example, ``[('Content-Type': 'text/cthulhu'), ('Token': 'boris')]``).
+        :type headers: ``list``
+        :param kwargs: Additional keyword arguments (optional). These arguments
+            are interpreted as the query part of the URL. The order of keyword 
+            arguments is not preserved in the request, but the keywords and 
+            their arguments will be URL encoded.
+        :type kwargs: ``dict``
+        :returns: A dictionary describing the response (see :class:`HttpLib` for
+            its structure).
+        :rtype: ``dict``
         """
         if headers is None: headers = []
         if kwargs: 
@@ -1016,19 +1033,22 @@ def get(self, url, headers=None, **kwargs):
         return self.request(url, { 'method': "GET", 'headers': headers })
 
     def post(self, url, headers=None, **kwargs):
-        """Issue a POST request to *url*.
-
-        *headers* should be a list of pairs specifying the headers for
-        the HTTP response (e.g., [('Content-Type': 'text/cthulhu'), ('Token': 'boris')]).
-
-        If ``post`` receives a keyword argument ``body``, it will use
-        its value as the body for the request, and encode the rest of the
-        keyword arguments into the URL's query as ``get`` or ``delete``
-        does. If there is no ``body`` keyword argument, then all the keyword
-        arguments are encoded into the body of the request in the
-        ``x-www-form-urlencoded`` format.
-
-        :returns: A dictionary describing the response (see ``HttpLib`` for its structure).
+        """Sends a POST request to a URL.
+
+        :param url: The URL.
+        :type url: ``string``
+        :param headers: A list of pairs specifying the headers for the HTTP 
+            response (for example, ``[('Content-Type': 'text/cthulhu'), ('Token': 'boris')]``).
+        :type headers: ``list``
+        :param kwargs: Additional keyword arguments (optional). If the argument 
+            is ``body``, the value is used as the body for the request, and the 
+            keywords and their arguments will be URL encoded. If there is no 
+            ``body`` keyword argument, all the keyword arguments are encoded 
+            into the body of the request in the format ``x-www-form-urlencoded``.
+        :type kwargs: ``dict``
+        :returns: A dictionary describing the response (see :class:`HttpLib` for
+            its structure).
+        :rtype: ``dict``
         """
         if headers is None: headers = []
         headers.append(("Content-Type", "application/x-www-form-urlencoded")),
@@ -1048,12 +1068,19 @@ def post(self, url, headers=None, **kwargs):
         return self.request(url, message)
 
     def request(self, url, message, **kwargs):
-        """Issue an HTTP request to *url*.
-
-        *message* should be a dictionary of the format understood
-        by the HTTP handler (see ``HttpLib`` for a description of
-        the format). Any additional keyword arguments are passed
-        unchanged to the handler.
+        """Issues an HTTP request to a URL.
+
+        :param url: The URL.
+        :type url: ``string``
+        :param message: A dictionary with the format as described in 
+            :class:`HttpLib`. 
+        :type message: ``dict``
+        :param kwargs: Additional keyword arguments (optional). These arguments
+            are passed unchanged to the handler.
+        :type kwargs: ``dict``
+        :returns: A dictionary describing the response (see :class:`HttpLib` for
+            its structure).
+        :rtype: ``dict``
         """
         response = self.handler(url, message, **kwargs)
         response = record(response)
diff --git a/splunklib/client.py b/splunklib/client.py
@@ -171,7 +171,7 @@ def _trailing(template, *targets):
     :type template: ``string``
     :param targets: Strings to successively match in *template*.
     :type targets: list of ``string``s
-    :return: Trailing string after all targets are matched.
+    :return: The trailing string after all targets are matched.
     :rtype: ``string``
     :raises ValueError: Raised when one of the targets does not match.
     """
@@ -417,8 +417,7 @@ def indexes(self):
     def info(self):
         """Returns the information about this instance of Splunk.
 
-        :return: The system information, as key-value pairs.
-        :rtype: ``dict``
+        :return: The system information, as a ``dict`` of key-value pairs.
         """
         response = self.get("server/info")
         return _filter_content(_load_atom(response, MATCH_ENTRY_CONTENT))
@@ -915,10 +914,6 @@ def _proper_namespace(self, owner=None, app=None, sharing=None):
         showing up due to wildcards in the service's namespace. We replace the wildcards with the
         namespace of the entity we want.
 
-        :param owner:
-        :param app:
-        :param sharing:
-        :return:
         """
         if owner is None and app is None and sharing is None and\
             (self.service.namespace.owner == '-' or self.service.namespace.app == '-'):
@@ -1023,8 +1018,7 @@ def links(self):
     def name(self):
         """Returns the entity name.
 
-        :return: The entity name.
-        :rtype: ``string``
+        :return: A ``string`` containing the entity name.
         """
         return self.state.title
 
@@ -1081,8 +1075,7 @@ def update(self, **kwargs):
         :param kwargs: Additional entity-specific arguments (optional).
         :type kwargs: ``dict``
 
-        :return: The entity this method is called on.
-        :rtype: class:`Entity`
+        :return: The :class:`Entity`.
         """
         # The peculiarity in question: the REST API creates a new
         # Entity if we pass name in the dictionary, instead of the
@@ -1689,11 +1682,11 @@ def _entity_path(self, state):
 class Stanza(Entity):
     """This class contains a single configuration stanza."""
     def submit(self, stanza):
-        """Sets the keys in *stanza* this Stanza.
+        """Sets the keys in this stanza.
 
-        :param stanza: A dictionary of key/value pairs to set in this stanza.
+        :param stanza: A dictionary of key-value pairs to set in this stanza.
         :type stanza: ``dict``
-        :return: The :class:`Stanza` object this method is called on.
+        :return: The :class:`Stanza` object.
         """
         body = _encode(**stanza)
         self.service.post(self.path, body=body)
@@ -1748,7 +1741,7 @@ def default(self):
     def delete(self, name):
         """ Deletes a given index. 
 
-        **Note**: This method is only supported in Splunk 5.0 and later.
+            **Note**: This method is only supported in Splunk 5.0 and later.
 
         :param name: The name of the index to delete.
         :type name: ``string``
@@ -1814,8 +1807,6 @@ def attached_socket(self, *args, **kwargs):
             stream.
         :type sourcetype: ``string``
 
-        :returns: Nothing.
-
         **Example**::
 
             import splunklib.client as client
@@ -1933,7 +1924,7 @@ def submit(self, event, host=None, source=None, sourcetype=None):
     def upload(self, filename, **kwargs):
         """Uploads a file for immediate indexing. 
         
-        **Note**: The file must be locally accessible from the server.
+            **Note**: The file must be locally accessible from the server.
         
         :param filename: The name of the file to upload. The file can be a 
             plain, compressed, or archived file.
@@ -1984,8 +1975,7 @@ def update(self, **kwargs):
             available parameters, see `Input parameters <http://dev.splunk.com/view/SP-CAAAEE6#inputparams>`_ on Splunk Developer Portal. 
         :type kwargs: ``dict`` 
         
-        :return: The input this method was called on.
-        :rtype: class:`Input`
+        :return: The :class:`Input`.
         """
         if self.kind not in ['tcp', 'splunktcp', 'tcp/raw', 'tcp/cooked']:
             result = super(Input, self).update(**kwargs)
@@ -2221,8 +2211,7 @@ def itemmeta(self, kind):
 
         :type kind: ``string``
         
-        :return: The metadata.
-        :rtype: class:``splunklib.data.Record``
+        :return: A :class:`splunklib.data.Record` containing the metadata.
         """
         response = self.get("%s/_new" % self._kindmap[kind])
         content = _load_atom(response, MATCH_ENTRY_CONTENT)
