Task #8721: some documentation for most important methods.

LTA/ltastorageoverview/lib/scraper.py

@@ -58,6 +58,7 @@ class FileInfo:
         return self.filename + " " + humanreadablesize(self.size) + " " + str(self.created_at)
 
 class SrmlsException(Exception):
+    '''Exception which is raised when an srmls command failes'''
     def __init__(self, command, exitcode, stdout, stderr):
         self.command = command
         self.exitcode = exitcode
@@ -69,6 +70,7 @@ class SrmlsException(Exception):
                 (self.command, self.exitcode, self.stdout, self.stderr)
 
 class ParseException(Exception):
+    '''Exception which is raised when parsing srmls results fails'''
     def __init__(self, message):
         self.message = message
 

LTA/ltastorageoverview/lib/store.py

@@ -34,11 +34,23 @@ logger = logging.getLogger(__name__)
 class EntryNotFoundException(Exception):
     pass
 
+
 class LTAStorageDb(PostgresDatabaseConnection):
+    """LTAStorageDb is a python API to the ltaso postgres database."""
+
     def __init__(self, dbcreds=None, log_queries=True):
+        """Create an instance of a LTAStorageDb
+        :param dbcredentials.DBCredentials dbcreds: the credential for logging in into the db
+        :param bool log_queries: do or don't log all queries
+        """
         super(LTAStorageDb, self).__init__(dbcreds=dbcreds, log_queries=log_queries)
 
     def insertSite(self, siteName, srmurl):
+        """insert a site into the database
+        :param string siteName: the name of the site
+        :param string srmurls: the srm url to that site
+        :return int: the new id of the inserted site
+        """
         site = self.siteByName(siteName)
 
         if site:
@@ -49,6 +61,13 @@ class LTAStorageDb(PostgresDatabaseConnection):
         return site_id
 
     def insertRootDirectory(self, siteName, rootDirectory):
+        """
+        Insert a root directory for a site. Each site has at least one root directory (with no parent).
+        For all non-root directories, use insertSubDirectory
+        :param string siteName: the name of the site (should already be in the database)
+        :param string rootDirectory: the full path of the directory
+        :return integer: the new id of the inserted root directory
+        """
         site = self.siteByName(siteName)
 
         if not site:
@@ -63,6 +82,12 @@ class LTAStorageDb(PostgresDatabaseConnection):
         return dir_id
 
     def insertSubDirectory(self, parent_dir_id, sub_directory_path):
+        """
+        Insert a sub directory which is a child of the directory with parent_dir_id
+        :param int parent_dir_id: the id of this subdirectories parent
+        :param string sub_directory_path: the full path of the subdirectory
+        :return integer: the new id of the inserted subdirectory
+        """
         result = self.executeQuery('insert into lta.directory (name, parent_dir_id) values (%s, %s) returning id;', (sub_directory_path, parent_dir_id), fetch=FETCH_ONE)
 
         if result and 'id' in result:
@@ -72,6 +97,12 @@ class LTAStorageDb(PostgresDatabaseConnection):
         return None
 
     def insertSubDirectories(self, subDirectoryPaths, parentDirId, directoryLastVisitTime = None):
+        """
+        Insert multiple sub directories which are all a child of the directory with parent_dir_id
+        :param int parent_dir_id: the id of this subdirectories parent
+        :param [string] subDirectoryPaths: a list of full paths of the subdirectories
+        :return [integer]: a list of new ids of the inserted subdirectories
+        """
         with self._connection.cursor() as cursor:
             insert_values = ','.join(cursor.mogrify('(%s, %s)', (name, parentDirId)) for name in subDirectoryPaths)
 
@@ -105,6 +136,11 @@ class LTAStorageDb(PostgresDatabaseConnection):
         return subDirIds
 
     def deleteDirectory(self, dir_id, commit=True):
+        """
+        delete the directory with id dir_id. Cascacades and also deletes all subdirs, files and stats under this directory.
+        :param int dir_id: the id of the directory to be deleted
+        :param bool commit: optional, commit directly when True
+        """
         self.executeQuery('DELETE FROM lta.directory where id = %s;', (dir_id,), fetch=FETCH_NONE)
 
         if commit: