[PATCH 2/2] livemedia-creator: Cleanup docstrings
Brian C. Lane
bcl at redhat.com
Fri May 9 18:48:40 UTC 2014
Start using Sphinx style docstrings.
---
src/sbin/livemedia-creator | 220 ++++++++++++++++++++++++++++++---------------
1 file changed, 150 insertions(+), 70 deletions(-)
diff --git a/src/sbin/livemedia-creator b/src/sbin/livemedia-creator
index c751858..91a2d61 100755
--- a/src/sbin/livemedia-creator
+++ b/src/sbin/livemedia-creator
@@ -76,8 +76,14 @@ class InstallError(Exception):
class LogRequestHandler(SocketServer.BaseRequestHandler):
"""
Handle monitoring and saving the logfiles from the virtual install
+
+ Incoming data is written to self.server.log_path and each line is checked
+ for patterns that would indicate that the installation failed.
+ self.server.log_error is set True when this happens.
"""
def setup(self):
+ """Start writing to self.server.log_path"""
+
if self.server.log_path:
self.fp = open(self.server.log_path, "w") # pylint: disable=attribute-defined-outside-init
else:
@@ -86,9 +92,12 @@ class LogRequestHandler(SocketServer.BaseRequestHandler):
def handle(self):
"""
- Handle writing incoming data to a logfile and
- checking the logs for any Tracebacks or other errors that indicate
- that the install failed.
+ Write incoming data to a logfile and check for errors
+
+ Split incoming data into lines and check for any Tracebacks or other
+ errors that indicate that the install failed.
+
+ Loops until self.server.kill is True
"""
line = ""
while True:
@@ -123,7 +132,9 @@ class LogRequestHandler(SocketServer.BaseRequestHandler):
def iserror(self, line):
"""
- Check a line to see if it contains an error indicating install failure
+ Check a line to see if it contains an error indicating installation failure
+
+ :param str line: log line to check for failure
"""
simple_tests = ["Traceback (",
"Out of memory:",
@@ -141,29 +152,45 @@ class LogRequestHandler(SocketServer.BaseRequestHandler):
class LogServer(SocketServer.TCPServer):
- """
- Add path to logfile
- Add log error flag
- Add a kill switch
- """
+ """A TCP Server that listens for log data"""
def __init__(self, log_path, *args, **kwargs):
+ """
+ Setup the log server
+
+ :param str log_path: Path to the log file to write
+ """
self.kill = False
self.log_error = False
self.log_path = log_path
SocketServer.TCPServer.__init__(self, *args, **kwargs)
def log_check(self):
+ """
+ Check to see if an error has been found in the log
+
+ :returns: True if there has been an error
+ :rtype: bool
+ """
return self.log_error
class LogMonitor(object):
"""
- Contains all the stuff needed to setup a thread to listen to the logs
- from the virtual install
+ Setup a server to monitor the logs output by the installation
+
+ This needs to be running before the virt-install runs, it expects
+ there to be a listener on the port used for the virtio log port.
"""
def __init__(self, log_path, host="localhost", port=0):
"""
- Fire up the thread listening for logs
+ Start a thread to monitor the logs.
+
+ :param str log_path: Path to the logfile to write
+ :param str host: Host to bind to. Default is localhost.
+ :param int port: Port to listen to or 0 to pick a port
+
+ If 0 is passed for the port the dynamically assigned port will be
+ available as self.port
"""
self.server = LogServer(log_path, (host, port), LogRequestHandler)
self.host, self.port = self.server.server_address
@@ -173,24 +200,31 @@ class LogMonitor(object):
self.server_thread.start()
def shutdown(self):
+ """Force shutdown of the monitoring thread"""
self.server.kill = True
self.server_thread.join()
class IsoMountpoint(object):
"""
- Mount the iso on a temporary directory and check to make sure the
- vmlinuz and initrd.img files exist
- Check the iso for a LiveOS directory and set a flag.
- Extract the iso's label.
+ Mount the iso and check to make sure the vmlinuz and initrd.img files exist
- initrd_path can be used to point to a boot.iso tree with a newer
- initrd.img than the iso has. The iso is still used for stage2.
+ Also check the iso for a LiveOS directory and set a flag and extract the
+ iso's label.
"""
- def __init__( self, iso_path, initrd_path=None ):
- """ iso_path is the path to a boot.iso
- initrd_path overrides mounting the iso for access to
- initrd and vmlinuz.
+ def __init__(self, iso_path, initrd_path=None):
+ """
+ Mount the iso
+
+ :param str iso_path: Path to the iso to mount
+ :param str initrd_path: Optional path to initrd
+
+ initrd_path can be used to point to a tree with a newer
+ initrd.img than the iso has. The iso is still used for stage2.
+
+ self.kernel and self.initrd point to the kernel and initrd.
+ self.liveos is set to True if there is a LiveOS/ directory
+ self.repo is the path to the mounted iso if there is a /repodata dir.
"""
self.label = None
self.iso_path = iso_path
@@ -221,12 +255,15 @@ class IsoMountpoint(object):
self.get_iso_label()
def umount( self ):
+ """Unmount the iso"""
if not self.initrd_path:
umount(self.mount_dir)
def get_iso_label(self):
"""
Get the iso's label using isoinfo
+
+ Sets self.label if one is found
"""
isoinfo_output = execWithCapture("isoinfo", ["-d", "-i", self.iso_path])
log.debug(isoinfo_output)
@@ -238,24 +275,30 @@ class IsoMountpoint(object):
class VirtualInstall(object):
"""
- Run virt-install using an iso and kickstart(s)
+ Run virt-install using an iso and a kickstart
"""
def __init__(self, iso, ks_paths, disk_img, img_size=2048,
kernel_args=None, memory=1024, vnc=None, arch=None,
log_check=None, virtio_host="127.0.0.1", virtio_port=6080,
qcow2=False):
"""
- iso is an instance of IsoMountpoint
- ks_paths is a list of paths to a kickstart files. All are injected, the
- first one is the one executed.
- disk_img is the path to a disk image (doesn't need to exist)
- img_size is the size, in MiB, of the image if it doesn't exist
- kernel_args are extra arguments to pass on the kernel cmdline
- memory is the amount of ram to assign to the virt
- vnc is passed to the --graphics command verbatim
- arch is the optional architecture to use in the virt
- log_check is a method that returns True of the log indicates an error
- virtio_host and virtio_port are used to communicate with the log monitor
+ Start the installation
+
+ :param iso: Information about the iso to use for the installation
+ :type iso: IsoMountpoint
+ :param list ks_paths: Paths to kickstart files. All are injected, the
+ first one is the one executed.
+ :param str disk_img: Path to a disk image, created it it doesn't exist
+ :param int img_size: The image size, in MiB, to create if it doesn't exist
+ :param str kernel_args: Extra kernel arguments to pass on the kernel cmdline
+ :param int memory: Amount of RAM to assign to the virt, in MiB
+ :param str vnc: Arguments to pass to virt-install --graphics
+ :param str arch: Optional architecture to use in the virt
+ :param log_check: Method that returns True if the installation fails
+ :type log_check: method
+ :param str virtio_host: Hostname to connect virtio log to
+ :param int virtio_port: Port to connect virtio log to
+ :param bool qcow2: Set to True if disk_img is a qcow2
"""
self.virt_name = "LiveOS-"+str(uuid.uuid4())
# add --graphics none later
@@ -346,7 +389,10 @@ class VirtualInstall(object):
def is_image_mounted(disk_img):
"""
- Return True if the disk_img is mounted
+ Check to see if the disk_img is mounted
+
+ :returns: True if disk_img is in /proc/mounts
+ :rtype: bool
"""
with open("/proc/mounts") as mounts:
for mnt in mounts:
@@ -357,8 +403,11 @@ def is_image_mounted(disk_img):
def get_arch(mount_dir):
- """ Return the arch of the first kernel at <mount_dir>/boot/
- or return i386
+ """
+ Get the kernel arch
+
+ :returns: Arch of first kernel found at mount_dir/boot/ or i386
+ :rtype: str
"""
kernels = findkernels(mount_dir)
if not kernels:
@@ -372,17 +421,17 @@ def make_appliance(disk_img, name, template, outfile, networks=None, ram=1024,
"""
Generate an appliance description file
- disk_img Full path of the disk image
- name Name of the appliance, passed to the template
- template Full path of Mako template
- outfile Full path of file to write, using template
- networks List of networks from the kickstart
- ram Ram, in MB, passed to template. Default is 1024
- vcpus CPUs, passed to template. Default is 1
- arch CPU architecture. Default is 'x86_64'
- title Title, passed to template. Default is 'Linux'
- project Project, passed to template. Default is 'Linux'
- releasever Release version, passed to template. Default is 17
+ :param str disk_img: Full path of the disk image
+ :param str name: Name of the appliance, passed to the template
+ :param str template: Full path of Mako template
+ :param str outfile: Full path of file to write, using template
+ :param list networks: List of networks(str) from the kickstart
+ :param int ram: Ram, in MiB, passed to template. Default is 1024
+ :param int vcpus: CPUs, passed to template. Default is 1
+ :param str arch: CPU architecture. Default is 'x86_64'
+ :param str title: Title, passed to template. Default is 'Linux'
+ :param str project: Project, passed to template. Default is 'Linux'
+ :param str releasever: Release version, passed to template. Default is 17
"""
if not (disk_img and template and outfile):
return None
@@ -420,10 +469,11 @@ def make_fsimage(diskimage, fsimage, img_size=None, label="Anaconda"):
Copy the / partition of a partitioned disk image to an un-partitioned
disk image.
- diskimage is the full path to partitioned disk image with a /
- fsimage is the full path of the output fs image file
- img_size is the size of the fsimage in MiB or None to make it as small as possible
- label is the label to apply to the image. Defaults to "Anaconda"
+ :param str diskimage: The full path to partitioned disk image with a /
+ :param str fsimage: The full path of the output fs image file
+ :param int img_size: Optional size of the fsimage in MiB or None to make
+ it as small as possible
+ :param str label: The label to apply to the image. Defaults to "Anaconda"
"""
with PartitionMount(diskimage) as img_mount:
if not img_mount or not img_mount.mount_dir:
@@ -441,7 +491,10 @@ def make_runtime(opts, mount_dir, work_dir):
"""
Make the squashfs image from a directory
- Result is in work_dir+RUNTIME
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ :param str mount_dir: Directory tree to compress
+ :param str work_dir: Output compressed image to work_dir+images/install.img
"""
kernel_arch = get_arch(mount_dir)
@@ -466,16 +519,16 @@ def make_livecd(opts, mount_dir, work_dir):
"""
Take the content from the disk image and make a livecd out of it
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ :param str mount_dir: Directory tree to compress
+ :param str work_dir: Output compressed image to work_dir+images/install.img
+
This uses wwood's squashfs live initramfs method:
* put the real / into LiveOS/rootfs.img
* make a squashfs of the LiveOS/rootfs.img tree
- * make a simple initramfs with the squashfs.img and /etc/cmdline in it
- * make a cpio of that tree
- * append the squashfs.cpio to a dracut initramfs for each kernel installed
-
- Then on boot dracut reads /etc/cmdline which points to the squashfs.img
- mounts that and then mounts LiveOS/rootfs.img as /
-
+ * This is loaded by dracut when the cmdline is passed to the kernel:
+ root=live:CDLABEL=<volid> rd.live.image
"""
kernel_arch = get_arch(mount_dir)
@@ -527,9 +580,15 @@ def novirt_install(opts, disk_img, disk_size, repo_url):
"""
Use Anaconda to install to a disk image
- disk_img is the full path to the disk image to be created
- disk_size is the size in MiB
- repo_url is the url of the repository to use for the installation
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ :param str disk_img: The full path to the disk image to be created
+ :param int disk_size: The size of the disk_img in MiB
+ :param str repo_url: The url of the repository to use for the installation
+
+ This method makes sure SELinux is permissive during the install, runs anaconda
+ to create the image and then based on the opts passed create a qcow2 image
+ or tarfile.
"""
import selinux
@@ -635,9 +694,14 @@ def virt_install(opts, install_log, disk_img, disk_size):
"""
Use virt-install to install to a disk image
- install_log is the path to write the log from virt-install
- disk_img is the full path to the final disk or filesystem image
- disk_size is the size of the disk to create in MiB
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ :param str install_log: The path to write the log from virt-install
+ :param str disk_img: The full path to the disk image to be created
+ :param int disk_size: The size of the disk_img in MiB
+
+ This uses virt-install with a boot.iso and a kickstart to create a disk
+ image and then optionally, based on the opts passed, creates tarfile.
"""
iso_mount = IsoMountpoint(opts.iso, opts.location)
log_monitor = LogMonitor(install_log)
@@ -694,8 +758,14 @@ def virt_install(opts, install_log, disk_img, disk_size):
def make_squashfs(disk_img, work_dir, compression="xz"):
"""
+ Create a squashfs image of an unpartitioned filesystem disk image
+
+ :param str disk_img: Path to the unpartitioned filesystem disk image
+ :param str work_dir: Output compressed image to work_dir+images/install.img
+ :param str compression: Compression type to use
+
Take disk_img and put it into LiveOS/rootfs.img and squashfs this
- tree into work_dir+RUNTIME
+ tree into work_dir+images/install.img
"""
liveos_dir = joinpaths(work_dir, "runtime/LiveOS")
os.makedirs(liveos_dir)
@@ -712,11 +782,15 @@ def make_squashfs(disk_img, work_dir, compression="xz"):
def make_image(opts, ks):
"""
- Install to an image
+ Install to a disk image
- Use virt or anaconda to install to an image.
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ :param str ks: Path to the kickstart to use for the installation
+ :returns: Path of the image created
+ :rtype: str
- Returns the full path of of the image created.
+ Use virt-install or anaconda to install to a disk image.
"""
disk_size = 1 + sum(p.size for p in ks.handler.partition.partitions)
log.info("disk_size = %sMiB", disk_size)
@@ -747,6 +821,12 @@ def make_image(opts, ks):
def setup_logging(opts):
+ """
+ Setup the various logs
+
+ :param opts: options passed to livemedia-creator
+ :type opts: argparse options
+ """
# Setup logging to console and to logfile
log.setLevel(logging.DEBUG)
pylorax_log.setLevel(logging.DEBUG)
--
1.9.0
More information about the anaconda-patches
mailing list