Start adding docstrings

2 files changed, 138 insertions, 8 deletions

diff --git a/obsapi/buildapi.py b/obsapi/buildapi.py
index 27e9124..d665612 100644
--- a/obsapi/buildapi.py
+++ b/obsapi/buildapi.py
@@ -1,9 +1,41 @@
 # -*- coding: utf-8 -*-
-#
+"""
+Python OBS 'source' API
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This module provides the ObsSourceAPI class used for accessing
+the `Open Build Service <https://openbuildservice.org/>'_ APIs
+related to `sources <https://build.opensuse.org/apidocs/index>`_.
+
+:copyright: Copyright (c) 2015-2020 Scott Bahling 
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License version 2 as
+    published by the Free Software Foundation.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program (see the file COPYING); if not, write to the
+    Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+:license: GPL-2.0, see COPYING for details
+"""
+
 from obsapi.httpapi import ObsHttpApi
 
 
 class ObsBuildApi(ObsHttpApi):
+    """Class for low level access to OBS 'build' apis.
+
+    This class of the provides get, put, post methods for accessing Open
+    Build Service APIs under base `/build` api route.
+
+    Attributes
+
+    """
 
     rootapi = '/build/'
 
@@ -17,11 +49,36 @@ class ObsBuildApi(ObsHttpApi):
         return super(ObsBuildApi, self).post(*args, **kwargs)
 
     def get(self, prj=None, repo=None, arch=None, pkg=None, binaryname=None,
-            view=None, binary_get=False, **kwargs):
-        if binaryname:
-            binary_get = True
+            **kwargs):
+        """
+        Send GET request to the OBS API under the '/build' route.
+
+        :param prj: OBS project name (Default value = None)
+        :param repo: Project repo name (Default value = None)
+        :param arch: Build architecture (Default value = None)
+        :param pkg: OBS package name (Default value = None)
+        :param binaryname: Build result binary file name (Default value = None)
+        :param **kwargs: HTTP query key/value pairs
+        :returns: content payload of the HTTP response as string or bytes
+
+        Calls GET build/<prj>/<repo>/<arch>/<pkg>/<binaryname>?<params>
+
+        """
+        errormsg = []
+        if binaryname and not pkg:
+            errormsg.append('Expect pkg argument when passing binaryname')
+        if pkg and not arch:
+            errormsg.append('Expect arch argument when passing pkg')
+        if arch and not repo:
+            errormsg.append('Expect repo argument when passing arch')
+        if repo and not prj:
+            errormsg.append('Expect prj argument when passing repo')
+        if errormsg:
+            raise ValueError('\n'.join(errormsg))
+
+        binary_get = (binaryname is not None)
         return self.__get(prj, repo, arch, pkg, binaryname,
-                          view=view, binary_get=binary_get, **kwargs)
+                          binary_get=binary_get, **kwargs)
 
     def get_builddepinfo(self, prj, repo, arch, pkg):
         return self.__get(prj, repo, arch, '_builddepinfo', package=pkg)
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)