Start adding docstrings

1 files changed, 76 insertions, 3 deletions

diff --git a/obsapi/httpapi.py b/obsapi/httpapi.py
index a06c525..92182c0 100644
--- a/obsapi/httpapi.py
+++ b/obsapi/httpapi.py
@@ -24,6 +24,34 @@ url_validate = re.compile(r'^(?:http|ftp)s?://'  # http:// or https://
 
 
 class ObsHttpApi(object):
+    """This class provides the lowest level OBS API HTTP interface
+
+    This class provides basic interfaces to GET, PUT, POST calls to the Open
+    Build Service API. The arguments to the get, put, post methods follow
+    the schema of the OBS API URL paths.
+
+    The class handles authentication using credentials setup with
+    the `osc` command or falls back to .netrc.
+
+    We don't do any real error checking here. Requests are sent to the
+    OBS api server and response results returned. Callers are expected
+    to interpret the results accordingly.
+
+    The ObsHttpApi class is usually subclassed by higher level
+    classes.
+
+    Parameters
+    ----------
+    apiurl: str
+        Base url for the OBS api server (i.e. https://api.opensuse.org)
+
+    Attributes
+    ----------
+    apiurl (str): The base url for the OBS api server.
+                  (i.e. https://api.opensuse.org)
+    verify_ssl (Boolean): Flag to verify ssl certificates
+
+    """
 
     default_xml = '<None/>'
     rootapi = '/'
@@ -53,6 +81,14 @@ class ObsHttpApi(object):
                 raise e
 
     def set_callback(self, func):
+        """
+        Setup a callback function that is called after each HTTP
+        request/response session to the OBS api server. This can
+        be used by callers to trap and check conditions after
+        calls (for example raising custom exceptions on HTTP errors).
+
+        :param func: function to call
+        """
         if isinstance(func, (types.FunctionType, types.MethodType)):
             self._callback_function = func
         else:
@@ -90,6 +126,7 @@ class ObsHttpApi(object):
         stream = params.pop('stream', False)
 
         def try_get():
+            """ """
             r = requests.get(url,
                              auth=self.__auth,
                              params=params,
@@ -133,6 +170,9 @@ class ObsHttpApi(object):
 
     @property
     def apiurl(self):
+        """
+        str:  The base url for the OBS api server.
+        """
         return self._apiurl
 
     @apiurl.setter
@@ -143,13 +183,13 @@ class ObsHttpApi(object):
 
     @property
     def response(self):
-        '''Return requests response from last api query'''
+        """python requests response obj: reference to the requests response
+           from the last HTTP call."""
         return self._response
 
     @property
     def success(self):
-        '''Return True if last api query was successful, else
-        return False'''
+        """bool: True if last HTTP call was successful"""
         return self._response.status_code == requests.codes.ok
 
     def __path(self, *args):
@@ -157,6 +197,25 @@ class ObsHttpApi(object):
         return '/'.join(['{}'] * len(args)).format(*args)
 
     def get(self, *args, **params):
+        """
+        Performs an HTTP GET request to the OBS API.
+
+        :param *args: arguments will be expanded to URL path elements.
+        :param **params: kwargs are converted to HTTP query arguments
+        :returns: content payload of the HTTP response as string or bytes.
+
+        Example:
+            >>> self.apiurl = 'https://api.opensuse.org'
+            >>> get('build', 'myproj', 'openSUSE_Tumbleweed',
+                    'x86_64', 'mypackage', 'filename', view='fileinfo')
+
+            results in the following HTTP call
+
+            GET "https://api.opensuse.org/build/myproj/openSUSE_Tumbleweed/x86_64/mypackage/filename?view=fileinfo"
+
+            and returns the xml payload of the OBS response.
+
+        """
         binary_get = params.pop('binary_get', False)
         path = self.__path(*args)
         stream = params.get('stream', False)
@@ -170,12 +229,26 @@ class ObsHttpApi(object):
         return r.text
 
     def put(self, *args, **kwargs):
+        """
+        Performs an HTTP PUT request to the OBS API.
+
+        :param *args: arguments will be expanded to URL path elements.
+        :param **params: kwargs are converted to HTTP query arguments
+        :returns: content payload of the HTTP response as string or bytes.
+        """
         data = kwargs.pop('data', None)
         path = self.__path(*args)
         r = self.__api_put(path, data=data, params=kwargs)
         return r
 
     def post(self, *args, **kwargs):
+        """
+        Performs an HTTP PUT request to the OBS API.
+
+        :param *args: arguments will be expanded to URL path elements.
+        :param **params: kwargs are converted to HTTP query arguments
+        :returns: content payload of the HTTP response as string or bytes.
+        """
         data = kwargs.pop('data', None)
         path = self.__path(*args)
         r = self.__api_post(path, data=data, params=kwargs)