Document basic classes and methods

image_creator/disk.py

@@ -19,8 +19,16 @@ class DiskError(Exception):
 
 
 class Disk(object):
+    """This class represents a hard disk hosting an Operating System
+
+    A Disk instance never alters the source media it is created from.
+    Any change is done on a snapshot created by the device-mapper of
+    the Linux kernel.
+    """
 
     def __init__(self, source):
+        """Create a new Disk instance out of a source media. The source
+        media can be an image file, a block device or a directory."""
         self._cleanup_jobs = []
         self._devices = []
         self.source = source
@@ -38,6 +46,9 @@ class Disk(object):
         raise NotImplementedError
 
     def cleanup(self):
+        """Cleanup internal data. This needs to be called before the
+        program ends.
+        """
         while len(self._devices):
             device = self._devices.pop()
             device.destroy()
@@ -47,6 +58,11 @@ class Disk(object):
             job(*args)
 
     def get_device(self):
+        """Returns a newly created DiskDevice instance.
+        
+        This instance is a snapshot of the original source media of
+        the Disk instance.
+        """
         sourcedev = self.source
         mode = os.stat(self.source).st_mode
         if stat.S_ISDIR(mode):
@@ -79,13 +95,20 @@ class Disk(object):
         return new_device
 
     def destroy_device(self, device):
+        """Destroys a DiskDevice instance previously created by
+        get_device method.
+        """
         self._devices.remove(device)
         device.destroy()
 
 
 class DiskDevice(object):
+    """This class represents a block device hosting an Operating System
+    as created by the device-mapper.
+    """
 
     def __init__(self, device, bootable=True):
+        """Create a new DiskDevice."""
         self.device = device
         self.bootable = bootable
 
@@ -106,13 +129,14 @@ class DiskDevice(object):
         self.distro = self.g.inspect_get_distro(self.root)
 
     def destroy(self):
+        """Destroy this DiskDevice instance."""
         self.g.umount_all()
         self.g.sync()
         # Close the guestfs handler
         self.g.close()
-        del self.g
 
     def mount(self):
+        """Mount all disk partitions in a correct order."""
         mps = self.g.inspect_get_mountpoints(self.root)
 
         # Sort the keys to mount the fs in a correct order.
@@ -132,9 +156,16 @@ class DiskDevice(object):
                 print "%s (ignored)" % msg
 
     def umount(self):
+        """Umount all mounted filesystems."""
         self.g.umount_all()
 
     def shrink(self):
+        """Shrink the disk.
+
+        This is accomplished by shrinking the last filesystem in the
+        disk and then updating the partition table. The new disk size
+        (in bytes) is returned.
+        """
         dev = self.g.part_to_dev(self.root)
         parttype = self.g.part_get_parttype(dev)
         if parttype != 'msdos':
@@ -167,5 +198,4 @@ class DiskDevice(object):
         return (end + 1) * sector_size
 
 
-
 # vim: set sta sts=4 shiftwidth=4 sw=4 et ai :

image_creator/main.py

@@ -51,9 +51,11 @@ def main():
         osclass = get_os_class(dev.distro, dev.ostype)
         image_os = osclass(dev.root, dev.g)
         metadata = image_os.get_metadata()
+        for key in metadata.keys():
+            print "%s=%s" % (key, metadata[key])
         image_os.data_cleanup()
         dev.umount()
-        dev.shrink()
+        #dev.shrink()
 
     finally:
         disk.cleanup()

image_creator/os_type/__init__.py

@@ -11,20 +11,36 @@ def add_prefix(target):
 
 
 class OSBase(object):
+    """Basic operating system class"""
     def __init__(self, rootdev, ghandler):
         self.root = rootdev
         self.g = ghandler
 
     @add_prefix
     def ls(self, directory):
+        """List the name of all files under a directory"""
         return self.g.ls(directory)
 
     @add_prefix
     def find(self, directory):
+        """List the name of all files recursively under a directory"""
         return self.g.find(directory)
 
     def foreach_file(self, directory, action, **kargs):
+        """Perform an action recursively on all files under a directory.
 
+        The following options are allowed:
+
+        * maxdepth: If defined the action will not be performed on
+          files that are below this level of directories under the
+          directory parameter.
+
+        * ftype: The action will only be performed on files of this
+          type. For a list of all allowed filetypes, see here:
+          http://libguestfs.org/guestfs.3.html#guestfs_readdir
+
+        * exclude: Exclude all files that follow this pattern.
+        """
         maxdepth = None if 'maxdepth' not in kargs else kargs['maxdepth']
         if maxdepth == 0:
             return
@@ -53,6 +69,7 @@ class OSBase(object):
                 action(full_path)
 
     def get_metadata(self):
+        """Returnes some descriptive metadata of the OS."""
         meta = {}
         meta["OSFAMILY"] = self.g.inspect_get_type(self.root)
         meta["OS"] = self.g.inspect_get_distro(self.root)
@@ -61,6 +78,7 @@ class OSBase(object):
         return meta
 
     def data_cleanup(self):
+        """Cleanup sesitive data out of the OS image."""
         raise NotImplementedError
 
 # vim: set sta sts=4 shiftwidth=4 sw=4 et ai :

image_creator/os_type/slackware.py

@@ -3,9 +3,9 @@ from image_creator.os_type.linux import Linux
 
 class Slackware(Linux):
     def cleanup_log(self):
-        # In slackware the the installed packages info are stored in
-        # /var/log/packages. Clearing all /var/log files will destroy
-        # the package management
+        # In slackware the metadata about installed packages are
+        # stored in /var/log/packages. Clearing all /var/log files
+        # will destroy the package management system.
         self.foreach_file('/var/log', self.g.truncate, ftype='r', \
             exclude='/var/log/packages')