Merge pull request #197 from calamares/Python_Docstrings

Python docstrings

src/modules/bootloader/main.py

@@ -32,6 +32,10 @@ from libcalamares.utils import check_chroot_call
 
 
 def get_uuid():
+    """ Checks and passes 'uuid' to other routine.
+
+    :return:
+    """
     root_mount_point = libcalamares.globalstorage.value("rootMountPoint")
     print("Root mount point: \"{!s}\"".format(root_mount_point))
     partitions = libcalamares.globalstorage.value("partitions")
@@ -44,6 +48,10 @@ def get_uuid():
 
 
 def get_bootloader_entry_name():
+    """ Passes 'bootloader_entry_name' to other routine based on configuration file.
+
+    :return:
+    """
     if "bootloaderEntryName" in libcalamares.job.configuration:
         return libcalamares.job.configuration["bootloaderEntryName"]
     else:
@@ -52,6 +60,11 @@ def get_bootloader_entry_name():
 
 
 def get_kernel_line(kernel_type):
+    """ Passes 'kernel_line' to other routine based on configuration file.
+
+    :param kernel_type:
+    :return:
+    """
     if kernel_type == "fallback":
         if "fallbackKernelLine" in libcalamares.job.configuration:
             return libcalamares.job.configuration["fallbackKernelLine"]
@@ -65,6 +78,12 @@ def get_kernel_line(kernel_type):
 
 
 def create_conf(uuid, conf_path, kernel_line):
+    """ Creates gummiboot configuration files based on given parameters.
+
+    :param uuid:
+    :param conf_path:
+    :param kernel_line:
+    """
     distribution = get_bootloader_entry_name()
     kernel = libcalamares.job.configuration["kernel"]
     img = libcalamares.job.configuration["img"]
@@ -91,6 +110,10 @@ def create_conf(uuid, conf_path, kernel_line):
 
 
 def create_loader(loader_path):
+    """ Writes configuration for loader.
+
+    :param loader_path:
+    """
     distribution = get_bootloader_entry_name()
     timeout = libcalamares.job.configuration["timeout"]
     file_name_sanitizer = str.maketrans(" /", "_-")
@@ -107,6 +130,10 @@ def create_loader(loader_path):
 
 
 def install_gummiboot(efi_directory):
+    """ Installs gummiboot as bootloader for EFI setups.
+
+    :param efi_directory:
+    """
     print("Bootloader: gummiboot")
     install_path = libcalamares.globalstorage.value("rootMountPoint")
     install_efi_directory = install_path + efi_directory
@@ -134,6 +161,11 @@ def install_gummiboot(efi_directory):
 
 
 def install_grub(efi_directory, fw_type):
+    """ Installs grub as bootloader, either in pc or efi mode.
+
+    :param efi_directory:
+    :param fw_type:
+    """
     if fw_type == "efi":
         print("Bootloader: grub (efi)")
         efi_directory_firmware = efi_directory + "/EFI"
@@ -166,6 +198,12 @@ def install_grub(efi_directory, fw_type):
 
 
 def prepare_bootloader(fw_type):
+    """ Prepares bootloader and set proper flags to EFI boot partition (esp,boot).
+    Based on value 'efi_boot_loader', it either calls gummiboot or grub to be installed.
+
+    :param fw_type:
+    :return:
+    """
     efi_boot_loader = libcalamares.job.configuration["efiBootLoader"]
     efi_directory = libcalamares.globalstorage.value("efiSystemPartition")
     if fw_type == "efi":
@@ -194,6 +232,10 @@ def prepare_bootloader(fw_type):
 
 
 def run():
+    """ Starts procedure and passes 'fw_type' to other routine.
+
+    :return:
+    """
     fw_type = libcalamares.globalstorage.value("firmwareType")
     prepare_bootloader(fw_type)
     return None

src/modules/displaymanager/main.py

@@ -3,7 +3,7 @@
 #
 # === This file is part of Calamares - <http://github.com/calamares> ===
 #
-#   Copyright 2014 - 2015, Philip Müller <philm@manjaro.org>
+#   Copyright 2014-2015, Philip Müller <philm@manjaro.org>
 #   Copyright 2014, Teo Mrnjavac <teo@kde.org>
 #   Copyright 2014, Kevin Kofler <kevin.kofler@chello.at>
 #
@@ -44,6 +44,11 @@ desktop_environments = [
 
 
 def find_desktop_environment(root_mount_point):
+    """ Checks which desktop environment is currently installed.
+
+    :param root_mount_point:
+    :return:
+    """
     for desktop_environment in desktop_environments:
         if os.path.exists(
                 "{!s}{!s}".format(root_mount_point, desktop_environment.executable)) \
@@ -54,6 +59,12 @@ def find_desktop_environment(root_mount_point):
 
 
 def have_dm(dm_name, root_mount_point):
+    """ Checks if display manager is properly installed.
+
+    :param dm_name:
+    :param root_mount_point:
+    :return:
+    """
     return os.path.exists(
         "{!s}/usr/bin/{!s}".format(root_mount_point, dm_name)) or os.path.exists(
         "{!s}/usr/sbin/{!s}".format(root_mount_point, dm_name))
@@ -61,8 +72,13 @@ def have_dm(dm_name, root_mount_point):
 
 def set_autologin(username, displaymanagers, default_desktop_environment,
                   root_mount_point):
-    """ Enables automatic login for the installed desktop managers """
+    """ Enables automatic login for the installed desktop managers.
 
+    :param username:
+    :param displaymanagers:
+    :param default_desktop_environment:
+    :param root_mount_point:
+    """
     if "mdm" in displaymanagers:
         # Systems with MDM as Desktop Manager
         mdm_conf_path = os.path.join(root_mount_point, "etc/mdm/custom.conf")
@@ -206,12 +222,13 @@ def set_autologin(username, displaymanagers, default_desktop_environment,
 
 
 def run():
-    """ Configure display managers """
-    # We acquire a list of displaymanagers, either from config or (overridden) from globalstorage.
-    # This module will try to set up (including autologin) all the displaymanagers in the list, in that specific order.
-    # Most distros will probably only ship one displaymanager.
-    # If a displaymanager is in the list but not installed, a debugging message is printed and the entry ignored.
-
+    """ Configure display managers.
+    
+    We acquire a list of displaymanagers, either from config or (overridden) from globalstorage.
+    This module will try to set up (including autologin) all the displaymanagers in the list, in that specific order.
+    Most distros will probably only ship one displaymanager.
+    If a displaymanager is in the list but not installed, a debugging message is printed and the entry ignored.
+    """
     if "displaymanagers" in libcalamares.job.configuration:
         displaymanagers = libcalamares.job.configuration["displaymanagers"]
 

src/modules/dracut/main.py

@@ -3,7 +3,7 @@
 #
 # === This file is part of Calamares - <http://github.com/calamares> ===
 #
-#   Copyright 2014, Philip Müller <philm@manjaro.org>
+#   Copyright 2014-2015, Philip Müller <philm@manjaro.org>
 #   Copyright 2014, Teo Mrnjavac <teo@kde.org>
 #
 #   Calamares is free software: you can redistribute it and/or modify
@@ -24,10 +24,18 @@ from libcalamares.utils import chroot_call
 
 
 def run_dracut():
+    """ Creates initramfs, even when initramfs already exists.
+
+    :return:
+    """
     return chroot_call(['dracut', '-f'])
 
 
 def run():
+    """ Starts routine to create initramfs. It passes back the exit code if it fails.
+
+    :return:
+    """
     returnCode = run_dracut()
     if returnCode != 0:
-        return ("Failed to run dracut on the target", "The exit code was {}".format(returnCode))
+        return ("Failed to run dracut on the target", "The exit code was {}".format(returnCode))

src/modules/dummypython/main.py

@@ -24,6 +24,15 @@ from time import gmtime, strftime
 
 
 def run():
+    """ Example Python jobmodule.
+
+    A Python jobmodule is a Python program which imports libcalamares and
+    has a function run() as entry point. run() must return None if everything
+    went well, or a tuple (str,str) with an error message and description 
+    if something went wrong.
+
+    :return:
+    """
     os.system("/bin/sh -c \"touch ~/calamares-dummypython\"")
     accumulator = strftime("%Y-%m-%d %H:%M:%S", gmtime()) + "\n"
     accumulator += "Calamares version: " + libcalamares.VERSION_SHORT + "\n"

src/modules/fstab/main.py

@@ -41,11 +41,20 @@ FS_MAP = {
 
 
 def mkdir_p(path):
+    """ Create directory.
+
+    :param path:
+    """
     if not os.path.exists(path):
         os.makedirs(path)
 
 
 def is_ssd_disk(disk_name):
+    """ Checks if given disk is actually a ssd disk.
+
+    :param disk_name:
+    :return:
+    """
     filename = os.path.join("/sys/block", disk_name, "queue/rotational")
     if not os.path.exists(filename):
         # Should not happen unless sysfs changes, but better safe than sorry
@@ -55,11 +64,24 @@ def is_ssd_disk(disk_name):
 
 
 def disk_name_for_partition(partition):
+    """ Returns disk name for each found partition.
+
+    :param partition:
+    :return:
+    """
     name = os.path.basename(partition["device"])
     return re.sub("[0-9]+$", "", name)
 
 
 class FstabGenerator(object):
+    """ Class header
+
+    :param partitions:
+    :param root_mount_point:
+    :param mount_options:
+    :param ssd_extra_mount_options:
+    """
+
     def __init__(self, partitions, root_mount_point, mount_options,
                  ssd_extra_mount_options):
         self.partitions = partitions
@@ -70,17 +92,22 @@ class FstabGenerator(object):
         self.root_is_ssd = False
 
     def run(self):
+        """ Calls needed sub routines.
+
+        :return:
+        """
         self.find_ssd_disks()
         self.generate_fstab()
         self.create_mount_points()
         return None
 
     def find_ssd_disks(self):
+        """ Checks for ssd disks """
         disks = {disk_name_for_partition(x) for x in self.partitions}
         self.ssd_disks = {x for x in disks if is_ssd_disk(x)}
 
     def generate_fstab(self):
-        # Create fstab
+        """ Create fstab. """
         mkdir_p(os.path.join(self.root_mount_point, "etc"))
         fstab_path = os.path.join(self.root_mount_point, "etc", "fstab")
         with open(fstab_path, "w") as fl:
@@ -102,6 +129,11 @@ class FstabGenerator(object):
                 self.print_fstab_line(dct, file=fl)
 
     def generate_fstab_line_info(self, partition):
+        """ Generates information for each fstab entry.
+
+        :param partition:
+        :return:
+        """
         fs = partition["fs"]
         mount_point = partition["mountPoint"]
         disk_name = disk_name_for_partition(partition)
@@ -136,6 +168,11 @@ class FstabGenerator(object):
             check=check)
 
     def print_fstab_line(self, dct, file=None):
+        """ Prints line to '/etc/fstab' file.
+
+        :param dct:
+        :param file:
+        """
         line = "{:41} {:<14} {:<7} {:<10} 0       {}".format(
             dct["device"],
             dct["mount_point"],
@@ -145,12 +182,17 @@ class FstabGenerator(object):
         print(line, file=file)
 
     def create_mount_points(self):
+        """ Creates mount points """
         for partition in self.partitions:
             if partition["mountPoint"]:
                 mkdir_p(self.root_mount_point + partition["mountPoint"])
 
 
 def run():
+    """ Configures fstab.
+
+    :return:
+    """
     gs = libcalamares.globalstorage
     conf = libcalamares.job.configuration
     partitions = gs.value("partitions")

src/modules/grubcfg/main.py

@@ -3,7 +3,7 @@
 #
 # === This file is part of Calamares - <http://github.com/calamares> ===
 #
-#   Copyright 2014 - 2015, Philip Müller <philm@manjaro.org>
+#   Copyright 2014-2015, Philip Müller <philm@manjaro.org>
 #
 #   Calamares is free software: you can redistribute it and/or modify
 #   it under the terms of the GNU General Public License as published by
@@ -23,6 +23,13 @@ import os
 
 
 def modify_grub_default(partitions, root_mount_point, distributor):
+    """ Configures '/etc/default/grub' for hibernation and plymouth.
+
+    :param partitions:
+    :param root_mount_point:
+    :param distributor:
+    :return:
+    """
     default_dir = os.path.join(root_mount_point, "etc/default")
     default_grub = os.path.join(default_dir, "grub")
     distributor_replace = distributor.replace("'", "'\\''")
@@ -95,6 +102,10 @@ def modify_grub_default(partitions, root_mount_point, distributor):
 
 
 def run():
+    """ Calls routine with given parameters to modify '/etc/default/grub'.
+
+    :return:
+    """
     partitions = libcalamares.globalstorage.value("partitions")
     root_mount_point = libcalamares.globalstorage.value("rootMountPoint")
     branding = libcalamares.globalstorage.value("branding")

src/modules/initcpio/main.py

@@ -23,10 +23,15 @@ from libcalamares.utils import check_chroot_call
 
 
 def run_mkinitcpio():
+    """ Runs mkinitcpio with given kernel profile """
     kernel = libcalamares.job.configuration['kernel']
     check_chroot_call(['mkinitcpio', '-p', kernel])
 
 
 def run():
+    """ Calls routine to create kernel initramfs image.
+
+    :return:
+    """
     run_mkinitcpio()
     return None

src/modules/initcpiocfg/main.py

@@ -26,13 +26,11 @@ from libcalamares.utils import check_chroot_call
 
 
 def cpuinfo():
-    """
-    Return the information in /proc/cpuinfo as a dictionary in the following format:
+    """ Return the information in /proc/cpuinfo as a dictionary in the following format:
+
     cpu_info['proc0']={...}
     cpu_info['proc1']={...}
-
     """
-
     cpuinfo = OrderedDict()
     procinfo = OrderedDict()
 
@@ -55,8 +53,12 @@ def cpuinfo():
 
 
 def set_mkinitcpio_hooks_and_modules(hooks, modules, root_mount_point):
-    """ Set up mkinitcpio.conf """
+    """ Set up mkinitcpio.conf.
 
+    :param hooks:
+    :param modules:
+    :param root_mount_point:
+    """
     with open("/etc/mkinitcpio.conf", "r") as mkinitcpio_file:
         mklins = [x.strip() for x in mkinitcpio_file.readlines()]
 
@@ -74,8 +76,11 @@ def set_mkinitcpio_hooks_and_modules(hooks, modules, root_mount_point):
 
 
 def modify_mkinitcpio_conf(partitions, root_mount_point):
-    """ Modifies mkinitcpio.conf """
+    """ Modifies mkinitcpio.conf
 
+    :param partitions:
+    :param root_mount_point:
+    """
     cpu = cpuinfo()
     swap_uuid = ""
     btrfs = ""
@@ -109,6 +114,10 @@ def modify_mkinitcpio_conf(partitions, root_mount_point):
 
 
 def run():
+    """ Calls routine with given parameters to modify '/etc/mkinitcpio.conf'.
+
+    :return:
+    """
     partitions = libcalamares.globalstorage.value("partitions")
     root_mount_point = libcalamares.globalstorage.value("rootMountPoint")
     modify_mkinitcpio_conf(partitions, root_mount_point)

src/modules/initramfs/main.py

@@ -22,6 +22,10 @@ from libcalamares.utils import chroot_call
 
 
 def run():
+    """ Generate an initramfs image.
+
+    :return:
+    """
     returnCode = chroot_call(["update-initramfs", "-k", "all", "-u"])
     if returnCode != 0:
         return ("Failed to run update-initramfs on the target", "The exit code was {}".format(returnCode))

src/modules/machineid/main.py

@@ -24,6 +24,10 @@ from libcalamares.utils import check_chroot_call
 
 
 def run():
+    """ Generate machine-id using dbus and systemd.
+
+    :return:
+    """
     root_mount_point = libcalamares.globalstorage.value("rootMountPoint")
     enable_systemd = libcalamares.job.configuration["systemd"]
     enable_dbus = libcalamares.job.configuration["dbus"]

src/modules/mount/main.py

@@ -24,6 +24,11 @@ import libcalamares
 
 
 def mount_partitions(root_mount_point, partitions):
+    """ Pass back mount point and filesystem for each partition.
+
+    :param root_mount_point:
+    :param partitions:
+    """
     for partition in partitions:
         if not partition["mountPoint"]:
             continue
@@ -44,6 +49,10 @@ def mount_partitions(root_mount_point, partitions):
 
 
 def run():
+    """ Define mountpoints.
+
+    :return:
+    """
     root_mount_point = tempfile.mkdtemp(prefix="calamares-root-")
     partitions = libcalamares.globalstorage.value("partitions")
     extra_mounts = libcalamares.job.configuration["extraMounts"]

src/modules/packages/main.py

@@ -23,10 +23,18 @@ from libcalamares.utils import check_chroot_call, chroot_call
 
 
 class PackageManager:
+    """ Package manager class.
+
+    :param backend:
+    """
     def __init__(self, backend):
         self.backend = backend
 
     def install(self, pkgs):
+        """ Installs packages.
+
+        :param pkgs:
+        """
         if self.backend == "packagekit":
             for pkg in pkgs:
                 check_chroot_call(["pkcon", "-py", "install", pkg])
@@ -48,6 +56,10 @@ class PackageManager:
             check_chroot_call(["pacman", "-Sy", "--noconfirm"] + pkgs)
 
     def remove(self, pkgs):
+        """ Removes packages.
+
+        :param pkgs:
+        """
         if self.backend == "packagekit":
             for pkg in pkgs:
                 check_chroot_call(["pkcon", "-py", "remove", pkg])
@@ -68,6 +80,11 @@ class PackageManager:
 
 
 def run_operations(pkgman, entry):
+    """ Call package manager with given parameters.
+
+    :param pkgman:
+    :param entry:
+    """
     for key in entry.keys():
         if key == "install":
             pkgman.install(entry[key])
@@ -76,6 +93,11 @@ def run_operations(pkgman, entry):
 
 
 def run():
+    """ Calls routine with detected package manager to install locale packages
+    or remove drivers not needed on the installed system.
+
+    :return:
+    """
     backend = libcalamares.job.configuration.get("backend")
     if backend not in ("packagekit", "zypp", "yum", "dnf", "urpmi", "apt", "pacman"):
         return ("Bad backend", "backend=\"{}\"".format(backend))

src/modules/testmodule.py

@@ -35,6 +35,13 @@ except ImportError:
 
 
 class Job:
+    """
+
+    :param working_path:
+    :param doc:
+    :param cfg_doc:
+    """
+
     def __init__(self, working_path, doc, cfg_doc):
         self.module_name = doc["name"]
         self.pretty_name = "Testing job " + doc["name"]
@@ -42,10 +49,19 @@ class Job:
         self.configuration = cfg_doc
 
     def setprogress(self, progress):
+        """
+
+        :param progress:
+        """
         print("Job set progress to {}%.".format(progress * 100))
 
 
 def main():
+    """
+
+
+    :return:
+    """
     parser = argparse.ArgumentParser()
     parser.add_argument("moduledir",
                         help="Dir containing the Python module.")

src/modules/umount/main.py

@@ -25,6 +25,11 @@ import libcalamares
 
 
 def list_mounts(root_mount_point):
+    """ List mount points.
+
+    :param root_mount_point:
+    :return:
+    """
     lst = []
     for line in open("/etc/mtab").readlines():
         device, mount_point, _ = line.split(" ", 2)
@@ -34,6 +39,10 @@ def list_mounts(root_mount_point):
 
 
 def run():
+    """ Unmounts given mountpoints in decreasing order.
+
+    :return:
+    """
     root_mount_point = libcalamares.globalstorage.value("rootMountPoint")
     if not root_mount_point:
         return ("No mount point for root partition in globalstorage",

src/modules/unpackfs/main.py

@@ -32,6 +32,12 @@ from libcalamares import *
 
 
 class UnpackEntry:
+    """ Extraction routine using rsync.
+
+    :param source:
+    :param sourcefs:
+    :param destination:
+    """
     __slots__ = ['source', 'sourcefs', 'destination', 'copied', 'total']
 
     def __init__(self, source, sourcefs, destination):
@@ -46,6 +52,11 @@ ON_POSIX = 'posix' in sys.builtin_module_names
 
 
 def list_excludes(destination):
+    """ List excludes for rsync.
+
+    :param destination:
+    :return:
+    """
     lst = []
     extra_mounts = globalstorage.value("extraMounts")
     for extra_mount in extra_mounts:
@@ -56,6 +67,13 @@ def list_excludes(destination):
 
 
 def file_copy(source, dest, progress_cb):
+    """ Extract given image using rsync.
+
+    :param source:
+    :param dest:
+    :param progress_cb:
+    :return:
+    """
     # Environment used for executing rsync properly
     # Setting locale to C (fix issue with tr_TR locale)
     at_env = os.environ
@@ -106,11 +124,16 @@ def file_copy(source, dest, progress_cb):
 
 
 class UnpackOperation:
+    """ Extraction routine using unsquashfs.
+
+    :param entries:
+    """
     def __init__(self, entries):
         self.entries = entries
         self.entry_for_source = dict((x.source, x) for x in self.entries)
 
     def report_progress(self):
+        """ Pass progress to user interface """
         progress = float(0)
         for entry in self.entries:
             if entry.total == 0:
@@ -124,6 +147,10 @@ class UnpackOperation:
         job.setprogress(progress)
 
     def run(self):
+        """ Extract given image using unsquashfs.
+
+        :return:
+        """
         source_mount_path = tempfile.mkdtemp()
         try:
             for entry in self.entries:
@@ -161,6 +188,11 @@ class UnpackOperation:
             shutil.rmtree(source_mount_path)
 
     def mount_image(self, entry, imgmountdir):
+        """ Mount given image as loop device.
+
+        :param entry:
+        :param imgmountdir:
+        """
         subprocess.check_call(["mount",
                                entry.source,
                                imgmountdir,
@@ -169,7 +201,18 @@ class UnpackOperation:
                                "-o", "loop"])
 
     def unpack_image(self, entry, imgmountdir):
+        """ Unpacks image.
+
+        :param entry:
+        :param imgmountdir:
+        :return:
+        """
+
         def progress_cb(copied):
+            """ Copies file to given destination target.
+
+            :param copied:
+            """
             entry.copied = copied
             self.report_progress()
 
@@ -182,20 +225,23 @@ class UnpackOperation:
 
 
 def run():
-    # from globalstorage: rootMountPoint
-    # from job.configuration:
-    # the path to where to mount the source image(s) for copying
-    # an ordered list of unpack mappings for image file <-> target dir relative
-    # to rootMountPoint, e.g.:
-    # configuration:
-    #     unpack:
-    #         - source: "/path/to/filesystem.img"
-    #           sourcefs: "ext4"
-    #           destination: ""
-    #         - source: "/path/to/another/filesystem.sqfs"
-    #           sourcefs: "squashfs"
-    #           destination: ""
-
+    """ Unsquashes filesystem from given image file.
+
+    from globalstorage: rootMountPoint
+    from job.configuration: the path to where to mount the source image(s) for copying
+    an ordered list of unpack mappings for image file <-> target dir relative
+    to rootMountPoint, e.g.:
+    configuration:
+        unpack:
+            - source: "/path/to/filesystem.img"
+              sourcefs: "ext4"
+              destination: ""
+            - source: "/path/to/another/filesystem.sqfs"
+              sourcefs: "squashfs"
+              destination: ""
+
+    :return:
+    """
     PATH_PROCFS = '/proc/filesystems'
 
     root_mount_point = globalstorage.value("rootMountPoint")