Augeas: Added docstrings, fixed some minor pylint issues

1 files changed, 91 insertions, 20 deletions

diff --git a/src/lib/Bcfg2/Client/Tools/POSIX/Augeas.py b/src/lib/Bcfg2/Client/Tools/POSIX/Augeas.py
index 55f3d5cf7..5e5412fed 100644
--- a/src/lib/Bcfg2/Client/Tools/POSIX/Augeas.py
+++ b/src/lib/Bcfg2/Client/Tools/POSIX/Augeas.py
@@ -7,36 +7,82 @@ from Bcfg2.Client.Tools.POSIX.base import POSIXTool
 
 
 class AugeasCommand(object):
-    def __init__(self, command, augeas, logger):
-        self.augeas = augeas
+    """ Base class for all Augeas command objects """
+
+    def __init__(self, command, augeas_obj, logger):
+        self._augeas = augeas_obj
         self.command = command
         self.entry = self.command.getparent()
         self.logger = logger
 
     def get_path(self, attr="path"):
+        """ Get a fully qualified path from the name of the parent entry and
+        the path given in this command tag.
+
+        @param attr: The attribute to get the relative path from
+        @type attr: string
+        @returns: string - the fully qualified Augeas path
+
+        """
         return "/files/%s/%s" % (self.entry.get("name").strip("/"),
                                  self.command.get(attr).lstrip("/"))
 
     def _exists(self, path):
-        return len(self.augeas.match(path)) > 1
+        """ Return True if a path exists in Augeas, False otherwise.
+
+        Note that a False return can mean many things: A file that
+        doesn't exist, a node within the file that doesn't exist, no
+        lens to parse the file, etc. """
+        return len(self._augeas.match(path)) > 1
 
     def _verify_exists(self, path=None):
+        """ Verify that the given path exists, with friendly debug
+        logging.
+
+        @param path: The path to verify existence of.  Defaults to the
+                     result of
+                     :func:`Bcfg2.Client.Tools.POSIX.Augeas.AugeasCommand.getpath`.
+        @type path: string
+        @returns: bool - Whether or not the path exists
+        """
         if path is None:
             path = self.get_path()
         self.logger.debug("Augeas: Verifying that '%s' exists" % path)
         return self._exists(path)
 
     def _verify_not_exists(self, path=None):
+        """ Verify that the given path does not exist, with friendly
+        debug logging.
+
+        @param path: The path to verify existence of.  Defaults to the
+                     result of
+                     :func:`Bcfg2.Client.Tools.POSIX.Augeas.AugeasCommand.getpath`.
+        @type path: string
+        @returns: bool - Whether or not the path does not exist.
+                  (I.e., True if it does not exist, False if it does
+                  exist.)
+        """
         if path is None:
             path = self.get_path()
         self.logger.debug("Augeas: Verifying that '%s' does not exist" % path)
         return not self._exists(path)
 
     def _verify_set(self, expected, path=None):
+        """ Verify that the given path is set to the given value, with
+        friendly debug logging.
+
+        @param expected: The expected value of the node.
+        @param path: The path to verify existence of.  Defaults to the
+                     result of
+                     :func:`Bcfg2.Client.Tools.POSIX.Augeas.AugeasCommand.getpath`.
+        @type path: string
+        @returns: bool - Whether or not the path matches the expected value.
+
+        """
         if path is None:
             path = self.get_path()
         self.logger.debug("Augeas: Verifying '%s' == '%s'" % (path, expected))
-        actual = self.augeas.get(path)
+        actual = self._augeas.get(path)
         if actual == expected:
             return True
         else:
@@ -47,19 +93,29 @@ class AugeasCommand(object):
     def __str__(self):
         return Bcfg2.Client.XML.tostring(self.command)
 
+    def verify(self):
+        """ Verify that the command has been applied. """
+        raise NotImplementedError
+
+    def install(self):
+        """ Run the command. """
+        raise NotImplementedError
+
 
 class Remove(AugeasCommand):
+    """ Augeas ``rm`` command """
     def verify(self):
         return self._verify_not_exists()
 
     def install(self):
         self.logger.debug("Augeas: Removing %s" % self.get_path())
-        return self.augeas.remove(self.get_path())
+        return self._augeas.remove(self.get_path())
 
 
 class Move(AugeasCommand):
-    def __init__(self, command, augeas, logger):
-        AugeasCommand.__init__(self, command, augeas, logger)
+    """ Augeas ``move`` command """
+    def __init__(self, command, augeas_obj, logger):
+        AugeasCommand.__init__(self, command, augeas_obj, logger)
         self.source = self.get_path("source")
         self.dest = self.get_path("destination")
 
@@ -69,12 +125,13 @@ class Move(AugeasCommand):
 
     def install(self):
         self.logger.debug("Augeas: Moving %s to %s" % (self.source, self.dest))
-        return self.augeas.move(self.source, self.dest)
+        return self._augeas.move(self.source, self.dest)
 
 
 class Set(AugeasCommand):
-    def __init__(self, command, augeas, logger):
-        AugeasCommand.__init__(self, command, augeas, logger)
+    """ Augeas ``set`` command """
+    def __init__(self, command, augeas_obj, logger):
+        AugeasCommand.__init__(self, command, augeas_obj, logger)
         self.value = self.command.get("value")
 
     def verify(self):
@@ -83,18 +140,20 @@ class Set(AugeasCommand):
     def install(self):
         self.logger.debug("Augeas: Setting %s to %s" % (self.get_path(),
                                                         self.value))
-        return self.augeas.set(self.get_path(), self.value)
+        return self._augeas.set(self.get_path(), self.value)
 
 
 class Clear(Set):
-    def __init__(self, command, augeas, logger):
-        Set.__init__(self, command, augeas, logger)
+    """ Augeas ``clear`` command """
+    def __init__(self, command, augeas_obj, logger):
+        Set.__init__(self, command, augeas_obj, logger)
         self.value = None
 
 
 class SetMulti(AugeasCommand):
-    def __init__(self, command, augeas, logger):
-        AugeasCommand.__init__(self, command, augeas, logger)
+    """ Augeas ``setm`` command """
+    def __init__(self, command, augeas_obj, logger):
+        AugeasCommand.__init__(self, command, augeas_obj, logger)
         self.sub = self.command.get("sub")
         self.value = self.command.get("value")
         self.base = self.get_path("base")
@@ -102,15 +161,16 @@ class SetMulti(AugeasCommand):
     def verify(self):
         return all(self._verify_set(self.value,
                                     path="%s/%s" % (path, self.sub))
-                   for path in self.augeas.match(self.base))
+                   for path in self._augeas.match(self.base))
 
     def install(self):
-        return self.augeas.setm(self.base, self.sub, self.value)
+        return self._augeas.setm(self.base, self.sub, self.value)
 
 
 class Insert(AugeasCommand):
-    def __init__(self, command, augeas, logger):
-        AugeasCommand.__init__(self, command, augeas, logger)
+    """ Augeas ``ins`` command """
+    def __init__(self, command, augeas_obj, logger):
+        AugeasCommand.__init__(self, command, augeas_obj, logger)
         self.label = self.command.get("label")
         self.where = self.command.get("where", "before")
         self.before = self.where == "before"
@@ -121,7 +181,7 @@ class Insert(AugeasCommand):
     def install(self):
         self.logger.debug("Augeas: Inserting new %s %s %s" %
                           (self.label, self.where, self.get_path()))
-        return self.augeas.insert(self.get_path(), self.label, self.before)
+        return self._augeas.insert(self.get_path(), self.label, self.before)
 
 
 class POSIXAugeas(POSIXTool):
@@ -136,6 +196,7 @@ class POSIXAugeas(POSIXTool):
         self._augeas = dict()
 
     def get_augeas(self, entry):
+        """ Get an augeas object for the given entry. """
         if entry.get("name") not in self._augeas:
             aug = augeas.augeas()
             if entry.get("lens"):
@@ -156,6 +217,16 @@ class POSIXAugeas(POSIXTool):
         return entry.text is not None
 
     def get_commands(self, entry, unverified=False):
+        """ Get a list of commands to verify or install.
+
+        @param entry: The entry to get commands from.
+        @type entry: lxml.etree._Element
+        @param unverified: Only get commands that failed verification.
+        @type unverified: bool
+        @returns: list of
+                  :class:`Bcfg2.Client.Tools.POSIX.Augeas.AugeasCommand`
+                  objects representing the commands.
+        """
         rv = []
         for cmd in entry.iterchildren():
             if unverified and cmd.get("verified", "false") != "false":