[yum-commits] Branch 'yum-3_2_X' - 2 commits - cli.py output.py

James Antill james at osuosl.org
Fri Jul 15 14:59:19 UTC 2011


 cli.py    |  467 +++++++++++++++++++++++++++++++++++---------
 output.py |  650 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 947 insertions(+), 170 deletions(-)

New commits:
commit 6f07032af6cb11468999f741bf1f45234bcc2ca9
Author: Nick Jacek <njacek at redhat.com>
Date:   Fri Jul 15 10:17:54 2011 -0400

    Adds documentation for the cli module.

diff --git a/cli.py b/cli.py
old mode 100644
new mode 100755
index 74504c4..43c0e1d
--- a/cli.py
+++ b/cli.py
@@ -51,23 +51,24 @@ from yum.i18n import to_unicode, to_utf8
 from yum.packages import parsePackages
 
 def sigquit(signum, frame):
-    """ SIGQUIT handler for the yum cli. """
+    """SIGQUIT handler for the yum cli.  This function will print an
+    error message and exit the program.
+    
+    :param signum: unused
+    :param frame: unused
+    """
     print >> sys.stderr, "Quit signal sent - exiting immediately"
     sys.exit(1)
 
 class CliError(yum.Errors.YumBaseError):
-
-    """
-    Command line interface related Exception.
-    """
+    """Command line interface related Exception."""
 
     def __init__(self, args=''):
         yum.Errors.YumBaseError.__init__(self)
         self.args = args
 
 class YumBaseCli(yum.YumBase, output.YumOutput):
-    """This is the base class for yum cli.
-       Inherits from yum.YumBase and output.YumOutput """
+    """This is the base class for yum cli."""
        
     def __init__(self):
         # handle sigquit early on
@@ -106,15 +107,24 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         self.registerCommand(yumcommands.LoadTransactionCommand())
 
     def registerCommand(self, command):
+        """Register a :class:`yumcommands.YumCommand` so that it can be called by
+        any of the names returned by its
+        :func:`yumcommands.YumCommand.getNames` method.
+        
+        :param command: the :class:`yumcommands.YumCommand` to register
+        """
         for name in command.getNames():
             if name in self.yum_cli_commands:
                 raise yum.Errors.ConfigError(_('Command "%s" already defined') % name)
             self.yum_cli_commands[name] = command
             
     def doRepoSetup(self, thisrepo=None, dosack=1):
-        """grabs the repomd.xml for each enabled repository 
-           and sets up the basics of the repository"""
-        
+        """Grab the repomd.xml for each enabled and set up the basics
+        of the repository.
+
+        :param thisrepo: the repository to set up
+        :param dosack: whether to get the repo sack
+        """
         if self._repos and thisrepo is None:
             return self._repos
             
@@ -183,10 +193,11 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         
         
     def getOptionsConfig(self, args):
-        """parses command line arguments, takes cli args:
-        sets up self.conf and self.cmds as well as logger objects 
-        in base instance"""
-       
+        """Parse command line arguments, and set up :attr:`self.conf` and
+        :attr:`self.cmds`, as well as logger objects in base instance.
+
+        :param args: a list of command line arguments
+        """
         self.optparser = YumOptionParser(base=self, usage=self._makeUsage())
         
         # Parse only command line options that affect basic yum setup
@@ -318,9 +329,11 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         time.sleep(sleeptime)
         
     def parseCommands(self):
-        """reads self.cmds and parses them out to make sure that the requested 
-        base command + argument makes any sense at all""" 
-
+        """Read :attr:`self.cmds` and parse them out to make sure that
+        the requested base command and argument makes any sense at
+        all.  This function will also set :attr:`self.basecmd` and
+        :attr:`self.extcmds`.
+        """
         self.verbose_logger.debug('Yum Version: %s', yum.__version__)
         self.verbose_logger.log(yum.logginglevels.DEBUG_4,
                                 'COMMAND: %s', self.cmdstring)
@@ -365,7 +378,11 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         self.history.write_addon_data('shell-cmds', data)
 
     def doShell(self):
-        """do a shell-like interface for yum commands"""
+        """Run a shell-like interface for yum commands.
+
+        :return: a tuple containing the shell result number, and the
+           shell result messages
+        """
 
         yumshell = shell.YumShell(base=self)
 
@@ -382,8 +399,12 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return yumshell.result, yumshell.resultmsgs
 
     def errorSummary(self, errstring):
-        """ parse the error string for 'interesting' errors which can
-            be grouped, such as disk space issues """
+        """Parse the error string for 'interesting' errors which can
+        be grouped, such as disk space issues.
+
+        :param errstring: the error string
+        :return: a string containing a summary of the errors
+        """
         summary = ''
         # do disk space report first
         p = re.compile('needs (\d+)MB on the (\S+) filesystem')
@@ -408,16 +429,17 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
 
 
     def doCommands(self):
-        """
-        Calls the base command passes the extended commands/args out to be
-        parsed (most notably package globs).
-        
-        Returns a numeric result code and an optional string
-           - 0 = we're done, exit
-           - 1 = we've errored, exit with error string
-           - 2 = we've got work yet to do, onto the next stage
-        """
-        
+        """Call the base command, and pass it the extended commands or
+           arguments.
+
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """       
         # at this point we know the args are valid - we don't know their meaning
         # but we know we're not being sent garbage
         
@@ -440,9 +462,13 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return self.yum_cli_commands[self.basecmd].doCommand(self, self.basecmd, self.extcmds)
 
     def doTransaction(self):
-        """takes care of package downloading, checking, user confirmation and actually
-           RUNNING the transaction"""
-    
+        """Take care of package downloading, checking, user
+        confirmation and actually running the transaction.
+
+        :return: a numeric return code, and optionally a list of
+           errors.  A negative return code indicates that errors
+           occurred in the pre-transaction checks
+        """
         # just make sure there's not, well, nothing to do
         if len(self.tsInfo) == 0:
             self.verbose_logger.info(_('Trying to run the transaction but nothing to do. Exiting.'))
@@ -609,12 +635,14 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return resultobject.return_code
         
     def gpgsigcheck(self, pkgs):
-        '''Perform GPG signature verification on the given packages, installing
-        keys if possible
+        """Perform GPG signature verification on the given packages,
+        installing keys if possible.
 
-        Returns non-zero if execution should stop (user abort).
-        Will raise YumBaseError if there's a problem
-        '''
+        :param pkgs: a list of package objects to verify the GPG
+           signatures of
+        :return: non-zero if execution should stop due to an error
+        :raises: Will raise :class:`YumBaseError` if there's a problem
+        """
         for po in pkgs:
             result, errmsg = self.sigCheckPkg(po)
 
@@ -693,11 +721,22 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
             self.verbose_logger.log(yum.logginglevels.INFO_2, msg)
 
     def installPkgs(self, userlist):
-        """Attempts to take the user specified list of packages/wildcards
-           and install them, or if they are installed, update them to a newer
-           version. If a complete version number if specified, attempt to 
-           upgrade (or downgrade if they have been removed) them to the
-           specified version"""
+        """Attempt to take the user specified list of packages or
+        wildcards and install them, or if they are installed, update
+        them to a newer version. If a complete version number is
+        specified, attempt to upgrade (or downgrade if they have been
+        removed) them to the specified version.
+
+        :param userlist: a list of names or wildcards specifying
+           packages to install
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         # get the list of available packages
         # iterate over the user's list
         # add packages to Transaction holding class if they match.
@@ -733,9 +772,27 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Nothing to do')]
         
     def updatePkgs(self, userlist, quiet=0, update_to=False):
-        """take user commands and populate transaction wrapper with 
-           packages to be updated"""
-        
+        """Take user commands and populate transaction wrapper with
+        packages to be updated.
+
+        :param userlist: a list of names or wildcards specifying
+           packages to update.  If *userlist* is an empty list, yum
+           will perform a global update
+        :param quiet: unused
+        :param update_to: if *update_to* is True, the update will only
+           be run if it will update the given package to the given
+           version.  For example, if the package foo-1-2 is installed,
+           updatePkgs(["foo-1-2], update_to=False) will work
+           identically to updatePkgs(["foo"]), but
+           updatePkgs(["foo-1-2"], update_to=True) will do nothing
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         # if there is no userlist, then do global update below
         # this is probably 90% of the calls
         # if there is a userlist then it's for updating pkgs, not obsoleting
@@ -771,9 +828,24 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
     #  Note that we aren't in __init__ yet for a couple of reasons, but we 
     # probably will get there for 3.2.28.
     def distroSyncPkgs(self, userlist):
-        """ This does either upgrade/downgrade, depending on if the latest
-            installed version is older or newer. We allow "selection" but not
-            local packages (use tmprepo, or something). """
+        """Upgrade or downgrade packages to match the latest versions
+        available in the enabled repositories.
+
+        :param userlist: list of names or wildcards specifying
+           packages to synchronize with the repositories.  If the
+           first string in *userlist* is "full", packages will also be
+           reinstalled if their checksums do not match the checksums
+           in the repositories.  If *userlist* is an empty list or
+           only contains "full", every installed package will be
+           synchronized
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
 
         level = 'diff'
         if userlist and userlist[0] in ('full', 'diff', 'different'):
@@ -867,9 +939,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
             return 0, [_('No Packages marked for Distribution Synchronization')]
 
     def erasePkgs(self, userlist):
-        """take user commands and populate a transaction wrapper with packages
-           to be erased/removed"""
-        
+        """Take user commands and populate a transaction wrapper with
+        packages to be erased.
+
+        :param userlist: a list of names or wildcards specifying
+           packages to erase
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         oldcount = len(self.tsInfo)
 
         all_rms = []
@@ -885,9 +967,20 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
             return 0, [_('No Packages marked for removal')]
     
     def downgradePkgs(self, userlist):
-        """Attempts to take the user specified list of packages/wildcards
-           and downgrade them. If a complete version number if specified,
-           attempt to downgrade them to the specified version"""
+        """Attempt to take the user specified list of packages or
+        wildcards and downgrade them. If a complete version number if
+        specified, attempt to downgrade them to the specified version
+
+        :param userlist: a list of names or wildcards specifying
+           packages to downgrade
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
 
         oldcount = len(self.tsInfo)
         
@@ -912,8 +1005,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Nothing to do')]
         
     def reinstallPkgs(self, userlist):
-        """Attempts to take the user specified list of packages/wildcards
-           and reinstall them. """
+        """Attempt to take the user specified list of packages or
+        wildcards and reinstall them.
+
+        :param userlist: a list of names or wildcards specifying
+           packages to reinstall
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
 
         oldcount = len(self.tsInfo)
 
@@ -947,9 +1051,18 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Nothing to do')]
 
     def localInstall(self, filelist, updateonly=0):
-        """handles installs/updates of rpms provided on the filesystem in a 
-           local dir (ie: not from a repo)"""
-           
+        """Install or update rpms provided on the file system in a
+        local directory (i.e. not from a repository).
+
+        :param filelist: a list of names specifying local rpms
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """           
         # read in each package into a YumLocalPackage Object
         # append it to self.localPackages
         # check if it can be installed or updated based on nevra versus rpmdb
@@ -973,20 +1086,25 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Nothing to do')]
 
     def returnPkgLists(self, extcmds, installed_available=False):
-        """Returns packages lists based on arguments on the cli.returns a 
-           GenericHolder instance with the following lists defined:
-           available = list of packageObjects
-           installed = list of packageObjects
-           updates = tuples of packageObjects (updating, installed)
-           extras = list of packageObjects
-           obsoletes = tuples of packageObjects (obsoleting, installed)
-           recent = list of packageObjects
-
-           installed_available = that the available package list is present
-                                 as .hidden_available when doing any of:
-                                 all/available/installed
-           """
-        
+        """Return a :class:`yum.misc.GenericHolder` object containing
+        lists of package objects that match the given names or wildcards.
+
+        :param extcmds: a list of names or wildcards specifying
+           packages to list
+        :param installed_available: whether the available package list
+           is present as .hidden_available when doing all, available,
+           or installed
+
+        :return: a :class:`yum.misc.GenericHolder` instance with the
+           following lists defined::
+
+             available = list of packageObjects
+             installed = list of packageObjects
+             updates = tuples of packageObjects (updating, installed)
+             extras = list of packageObjects
+             obsoletes = tuples of packageObjects (obsoleting, installed)
+             recent = list of packageObjects
+        """
         special = ['available', 'installed', 'all', 'extras', 'updates', 'recent',
                    'obsoletes']
         
@@ -1018,8 +1136,25 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return ypl
 
     def search(self, args):
-        """cli wrapper method for module search function, searches simple
-           text tags in a package object"""
+        """Search for simple text tags in a package object. This is a
+        cli wrapper method for the module search function.
+
+        :param args: list of names or wildcards to search for.
+           Normally this method will begin by searching the package
+           names and summaries, and will only search urls and
+           descriptions if that fails.  However, if the first string
+           in *args* is "all", this method will always search
+           everything
+        :return: a tuple where the first item is an exit code, and
+           the second item is a generator if the search is a
+           successful, and a list of error messages otherwise
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         
         # call the yum module search function with lists of tags to search
         # and what to search for
@@ -1109,9 +1244,20 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, matching
 
     def deplist(self, args):
-        """cli wrapper method for findDeps method takes a list of packages and 
-            returns a formatted deplist for that package"""
+        """Print out a formatted list of dependencies for a list of
+        packages.  This is a cli wrapper method for
+        :class:`yum.YumBase.findDeps`.
 
+        :param args: a list of names or wildcards specifying packages
+           that should have their dependenices printed
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         pkgs = []
         for arg in args:
             if (arg.endswith('.rpm') and (yum.misc.re_remote_url(arg) or
@@ -1132,10 +1278,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, []
 
     def provides(self, args):
-        """use the provides methods in the rpmdb and pkgsack to produce a list 
-           of items matching the provides strings. This is a cli wrapper to the 
-           module"""
-        
+        """Print out a list of packages that provide the given file or
+        feature.  This a cli wrapper to the provides methods in the
+        rpmdb and pkgsack.
+
+        :param args: the name of a file or feature to search for
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         old_sdup = self.conf.showdupesfromrepos
         # For output, as searchPackageProvides() is always in showdups mode
         self.conf.showdupesfromrepos = True
@@ -1164,8 +1319,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, []
     
     def resolveDepCli(self, args):
-        """returns a package (one per user arg) that provide the supplied arg"""
-        
+        """Print information about a package that provides the given
+        dependency.  Only one package will be printed per dependency.
+
+        :param args: a list of strings specifying dependencies to
+           search for
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         for arg in args:
             try:
                 pkg = self.returnPackageByDep(arg)
@@ -1178,6 +1344,34 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, []
     
     def cleanCli(self, userlist):
+        """Remove data from the yum cache directory.  What data is
+        removed depends on the options supplied by the user.
+
+        :param userlist: a list of options.  The following are valid
+           options::
+
+             expire-cache = Eliminate the local data saying when the
+               metadata and mirror lists were downloaded for each
+               repository.
+             packages = Eliminate any cached packages
+             headers = Eliminate the header files, which old versions
+               of yum used for dependency resolution
+             metadata = Eliminate all of the files which yum uses to
+               determine the remote availability of packages
+             dbcache = Eliminate the sqlite cache used for faster
+               access to metadata
+             rpmdb = Eliminate any cached datat from the local rpmdb
+             plugins = Tell any enabled plugins to eliminate their
+               cached data
+             all = do all of the above
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         hdrcode = pkgcode = xmlcode = dbcode = expccode = 0
         pkgresults = hdrresults = xmlresults = dbresults = expcresults = []
         msg = self.fmtKeyValFill(_('Cleaning repos: '), 
@@ -1229,7 +1423,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return code, []
 
     def returnGroupLists(self, userlist):
+        """Print out a list of groups that match the given names or
+        wildcards.
+
+        :param extcmds: a list of names or wildcards specifying
+           groups to list
+        :return: (exit_code, [ errors ])
 
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage        
+        """
         uservisible=1
             
         if len(userlist) > 0:
@@ -1284,7 +1490,20 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Done')]
 
     def returnGroupSummary(self, userlist):
+        """Print a summary of the groups that match the given names or
+        wildcards.
+
+        :param userlist: a list of names or wildcards specifying the
+           groups to summarise. If *userlist* is an empty list, all
+           installed and available packages will be summarised
+        :return: (exit_code, [ errors ])
 
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         uservisible=1
             
         if len(userlist) > 0:
@@ -1328,7 +1547,19 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, [_('Done')]
     
     def returnGroupInfo(self, userlist):
-        """returns complete information on a list of groups"""
+        """Print complete information about the groups that match the
+        given names or wildcards.
+
+        :param userlist: a list of names or wildcards specifying the
+           groups to print information about
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         for strng in userlist:
             group_matched = False
             for group in self.comps.return_groups(strng):
@@ -1341,8 +1572,18 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return 0, []
         
     def installGroups(self, grouplist):
-        """for each group requested do 'selectGroup' on them."""
-        
+        """Mark the packages in the given groups for installation.
+
+        :param grouplist: a list of names or wildcards specifying
+           groups to be installed
+        :return: (exit_code, [ errors ])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         pkgs_used = []
         
         for group_string in grouplist:
@@ -1369,8 +1610,18 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
             return 2, [P_('%d package to Install', '%d packages to Install', len(pkgs_used)) % len(pkgs_used)]
 
     def removeGroups(self, grouplist):
-        """Remove only packages of the named group(s). Do not recurse."""
+        """Mark the packages in the given groups for removal.
+
+        :param grouplist: a list of names or wildcards specifying
+           groups to be removed
+        :return: (exit_code, [ errors ])
 
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+            2 = we've got work yet to do, onto the next stage
+        """
         pkgs_used = []
         for group_string in grouplist:
             try:
@@ -1408,11 +1659,11 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return False
 
     def usage(self):
-        ''' Print out command line usage '''
+        """Print out an explanation of command line usage."""
         sys.stdout.write(self.optparser.format_help())
 
     def shellUsage(self):
-        ''' Print out the shell usage '''
+        """Print out an explanation of the shell usage."""
         sys.stdout.write(self.optparser.get_usage())
     
     def _installable(self, pkg, ematch=False):
@@ -1468,9 +1719,9 @@ class YumBaseCli(yum.YumBase, output.YumOutput):
         return False
 
 class YumOptionParser(OptionParser):
-    '''Subclass that makes some minor tweaks to make OptionParser do things the
+    """Subclass that makes some minor tweaks to make OptionParser do things the
     "yum way".
-    '''
+    """
 
     def __init__(self,base, **kwargs):
         # check if this is called with a utils=True/False parameter
@@ -1488,13 +1739,23 @@ class YumOptionParser(OptionParser):
         self._addYumBasicOptions()
 
     def error(self, msg):
-        '''This method is overridden so that error output goes to logger. '''
+        """Output an error message, and exit the program.  This method
+        is overridden so that error output goes to the logger.
+
+        :param msg: the error message to output
+        """
         self.print_usage()
         self.logger.critical(_("Command line error: %s"), msg)
         sys.exit(1)
 
     def firstParse(self,args):
-        # Parse only command line options that affect basic yum setup
+        """Parse only command line options that affect basic yum
+        setup.
+
+        :param args: a list of command line options to parse
+        :return: a dictionary containing the values of command line
+           options
+        """
         try:
             args = _filtercmdline(
                         ('--noplugins','--version','-q', '-v', "--quiet", "--verbose"), 
@@ -1521,7 +1782,15 @@ class YumOptionParser(OptionParser):
         return ret
         
     def setupYumConfig(self, args=None):
-        # Now parse the command line for real
+        """Parse command line options.
+
+        :param args: the command line arguments entered by the user
+        :return: (opts, cmds)  opts is a dictionary containing
+           the values of command line options.  cmds is a list of the
+           command line arguments that were not parsed as options.
+           For example, if args is ["install", "foo", "--verbose"],
+           cmds will be ["install", "foo"].
+        """
         if not args:
             (opts, cmds) = self.parse_args()
         else:
@@ -1642,6 +1911,14 @@ class YumOptionParser(OptionParser):
         sys.exit(1)
 
     def getRoot(self,opts):
+        """Return the root location to use for the yum operation.
+        This location can be changed by using the --installroot
+        option.
+
+        :param opts: a dictionary containing the values of the command
+           line options
+        :return: a string representing the root location
+        """
         self._checkAbsInstallRoot(opts)
         # If the conf file is inside the  installroot - use that.
         # otherwise look for it in the normal root
commit 5f7c87cf90fabd6c48208137cc9770bdcf991b40
Author: Nick Jacek <njacek at redhat.com>
Date:   Fri Jul 15 10:07:05 2011 -0400

    Adds documentation for the output module.
    
    I fixed up the issues you pointed out.

diff --git a/output.py b/output.py
index 94cbc64..9610232 100755
--- a/output.py
+++ b/output.py
@@ -1,6 +1,6 @@
 #!/usr/bin/python -t
 
-"""This handles actual output from the cli"""
+"""Handle actual output from the cli."""
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -60,17 +60,21 @@ def _term_width():
 
 
 class YumTextMeter(TextMeter):
-
-    """
-    Text progress bar output.
-    """
+    """A class to display text progress bar output."""
 
     def update(self, amount_read, now=None):
+        """Update the status of the text progress bar
+
+        :param amount_read: the amount of data, in bytes, that has been read
+        :param now: the current time in seconds since the epoch.  If
+           *now* is not given, the output of :func:`time.time()` will
+           be used.
+        """
         checkSignals()
         TextMeter.update(self, amount_read, now)
 
 class YumTerm:
-    """some terminal "UI" helpers based on curses"""
+    """A class to provide some terminal "UI" helpers based on curses."""
 
     # From initial search for "terminfo and python" got:
     # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/475116
@@ -145,6 +149,17 @@ class YumTerm:
         self.BG_COLOR = self.__ansi_forced_BG_COLOR
 
     def reinit(self, term_stream=None, color='auto'):
+        """Reinitializes the :class:`YumTerm`.
+
+        :param term_stream:  the terminal stream that the
+           :class:`YumTerm` should be initialized to use.  If
+           *term_stream* is not given, :attr:`sys.stdout` is used.
+        :param color: when to colorize output.  Valid values are
+           'always', 'auto', and 'never'.  'always' will use ANSI codes
+           to always colorize output, 'auto' will decide whether do
+           colorize depending on the terminal, and 'never' will never
+           colorize.
+        """
         self.__enabled = True
         if not hasattr(urlgrabber.progress, 'terminal_width_cached'):
             self.columns = 80
@@ -255,6 +270,37 @@ class YumTerm:
         return re.sub(r'\$<\d+>[/*]?', '', cap)
 
     def sub(self, haystack, beg, end, needles, escape=None, ignore_case=False):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        *beg*, and postfix each occurrence with *end*, then return the
+        modified string.  For example::
+           
+           >>> yt = YumTerm()
+           >>> yt.sub('spam and eggs', 'x', 'z', ['and'])
+           'spam xandz eggs'
+
+        This is particularly useful for emphasizing certain words
+        in output: for example, calling :func:`sub` with *beg* =
+        MODE['bold'] and *end* = MODE['normal'] will return a string
+        that when printed to the terminal will appear to be *haystack*
+        with each occurrence of the strings in *needles* in bold
+        face.  Note, however, that the :func:`sub_mode`,
+        :func:`sub_bold`, :func:`sub_fg`, and :func:`sub_bg` methods
+        provide convenient ways to access this same emphasizing functionality. 
+
+        :param haystack: the string to be modified
+        :param beg: the string to be prefixed onto matches
+        :param end: the string to be postfixed onto matches
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :param escape: a function that accepts a string and returns
+           the same string with problematic characters escaped.  By
+           default, :func:`re.escape` is used.
+        :param ignore_case: whether case should be ignored when
+           searching for matches
+        :return: *haystack* with *beg* prefixing, and *end*
+          postfixing, occurrences of the strings in *needles*
+        """
         if not self.__enabled:
             return haystack
 
@@ -269,27 +315,106 @@ class YumTerm:
             haystack = re.sub(pat, render, haystack)
         return haystack
     def sub_norm(self, haystack, beg, needles, **kwds):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        *beg*, and postfix each occurrence with self.MODE['normal'],
+        then return the modified string.  If *beg* is an ANSI escape
+        code, such as given by self.MODE['bold'], this method will
+        return *haystack* with the formatting given by the code only
+        applied to the strings in *needles*.
+
+        :param haystack: the string to be modified
+        :param beg: the string to be prefixed onto matches
+        :param end: the string to be postfixed onto matches
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :return: *haystack* with *beg* prefixing, and self.MODE['normal']
+          postfixing, occurrences of the strings in *needles*
+        """
         return self.sub(haystack, beg, self.MODE['normal'], needles, **kwds)
 
     def sub_mode(self, haystack, mode, needles, **kwds):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        self.MODE[*mode*], and postfix each occurrence with
+        self.MODE['normal'], then return the modified string.  This
+        will return a string that when printed to the terminal will
+        appear to be *haystack* with each occurrence of the strings in
+        *needles* in the given *mode*.
+
+        :param haystack: the string to be modified
+        :param mode: the mode to set the matches to be in.  Valid
+           values are given by self.MODE.keys().
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :return: *haystack* with self.MODE[*mode*] prefixing, and
+          self.MODE['normal'] postfixing, occurrences of the strings
+          in *needles*
+        """
         return self.sub_norm(haystack, self.MODE[mode], needles, **kwds)
 
     def sub_bold(self, haystack, needles, **kwds):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        self.MODE['bold'], and postfix each occurrence with
+        self.MODE['normal'], then return the modified string.  This
+        will return a string that when printed to the terminal will
+        appear to be *haystack* with each occurrence of the strings in
+        *needles* in bold face.
+
+        :param haystack: the string to be modified
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :return: *haystack* with self.MODE['bold'] prefixing, and
+          self.MODE['normal'] postfixing, occurrences of the strings
+          in *needles*
+        """
         return self.sub_mode(haystack, 'bold', needles, **kwds)
     
     def sub_fg(self, haystack, color, needles, **kwds):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        self.FG_COLOR[*color*], and postfix each occurrence with
+        self.MODE['normal'], then return the modified string.  This
+        will return a string that when printed to the terminal will
+        appear to be *haystack* with each occurrence of the strings in
+        *needles* in the given color.
+
+        :param haystack: the string to be modified
+        :param color: the color to set the matches to be in.  Valid
+           values are given by self.FG_COLOR.keys().
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :return: *haystack* with self.FG_COLOR[*color*] prefixing, and
+          self.MODE['normal'] postfixing, occurrences of the strings
+          in *needles*
+        """
         return self.sub_norm(haystack, self.FG_COLOR[color], needles, **kwds)
 
     def sub_bg(self, haystack, color, needles, **kwds):
+        """Search the string *haystack* for all occurrences of any
+        string in the list *needles*.  Prefix each occurrence with
+        self.BG_COLOR[*color*], and postfix each occurrence with
+        self.MODE['normal'], then return the modified string.  This
+        will return a string that when printed to the terminal will
+        appear to be *haystack* with each occurrence of the strings in
+        *needles* highlighted in the given background color.
+
+        :param haystack: the string to be modified
+        :param color: the background color to set the matches to be in.  Valid
+           values are given by self.BG_COLOR.keys().
+        :param needles: a list of strings to add the prefixes and
+           postfixes to
+        :return: *haystack* with self.BG_COLOR[*color*] prefixing, and
+          self.MODE['normal'] postfixing, occurrences of the strings
+          in *needles*
+        """
         return self.sub_norm(haystack, self.BG_COLOR[color], needles, **kwds)
 
 
 
 class YumOutput:
-
-    """
-    Main output class for the yum command line.
-    """
+    """Main output class for the yum command line."""
 
     def __init__(self):
         self.logger = logging.getLogger("yum.cli")
@@ -304,6 +429,12 @@ class YumOutput:
 
     
     def printtime(self):
+        """Return a string representing the current time in the form::
+
+           Mon dd hh:mm:ss
+
+        :return: a string representing the current time
+        """
         months = [_('Jan'), _('Feb'), _('Mar'), _('Apr'), _('May'), _('Jun'),
                   _('Jul'), _('Aug'), _('Sep'), _('Oct'), _('Nov'), _('Dec')]
         now = time.localtime(time.time())
@@ -312,14 +443,27 @@ class YumOutput:
         return ret
          
     def failureReport(self, errobj):
-        """failure output for failovers from urlgrabber"""
-        
+        """Perform failure output for failovers from urlgrabber
+
+        :param errobj: :class:`urlgrabber.grabber.CallbackObject`
+           containing information about the error
+        :raises: *errobj*.exception
+        """
         self.logger.error('%s: %s', errobj.url, errobj.exception)
         self.logger.error(_('Trying other mirror.'))
         raise errobj.exception
     
         
     def simpleProgressBar(self, current, total, name=None):
+        """Output the current status to the terminal using a simple
+        status bar.
+
+        :param current: a number representing the amount of work
+           already done
+        :param total: a number representing the total amount of work
+           to be done
+        :param name: a name to label the progress bar with
+        """
         progressbar(current, total, name)
 
     def _highlight(self, highlight):
@@ -368,9 +512,29 @@ class YumOutput:
 
     def calcColumns(self, data, columns=None, remainder_column=0,
                     total_width=None, indent=''):
-        """ Dynamically calculate the width of the fields in the data, data is
-            of the format [column-number][field_length] = rows. """
-
+        """Dynamically calculate the widths of the columns that the
+        fields in data should be placed into for output.
+        
+        :param data: a list of dictionaries that represent the data to
+           be output.  Each dictionary in the list corresponds to a
+           column of output. The keys of the dictionary are the
+           lengths of the items to be output, and the value associated
+           with a key is the number of items of that length.
+        :param columns: a list containing the minimum amount of space
+           that must be allocated for each row. This can be used to
+           ensure that there is space available in a column if, for
+           example, the actual lengths of the items being output
+           cannot be given in *data*
+        :param remainder_column: number of the column to receive a few
+           extra spaces that may remain after other allocation has
+           taken place
+        :param total_width: the total width of the output.
+           self.term.columns is used by default
+        :param indent: string that will be prefixed to a line of
+           output to create e.g. an indent
+        :return: a list of the widths of the columns that the fields
+           in data should be placed into for output
+        """
         if total_width is None:
             total_width = self.term.columns
 
@@ -473,10 +637,20 @@ class YumOutput:
         return (val, width, hibeg, hiend)
 
     def fmtColumns(self, columns, msg=u'', end=u'', text_width=utf8_width):
-        """ Return a string for columns of data, which can overflow.
-            text_width parameter finds the width of columns, this defaults to
-            utf8 but can be changed to len() if you know it'll be fine. """
-
+        """Return a row of data formatted into a string for output.
+        Items can overflow their columns. 
+
+        :param columns: a list of tuples containing the data to
+           output.  Each tuple contains first the item to be output,
+           then the amount of space allocated for the column, and then
+           optionally a type of highlighting for the item
+        :param msg: a string to begin the line of output with
+        :param end: a string to end the line of output with
+        :param text_width: a function to find the width of the items
+           in the columns.  This defaults to utf8 but can be changed
+           to len() if you know it'll be fine
+        :return: a row of data formatted into a string for output
+        """
         total_width = len(msg)
         data = []
         for col_data in columns[:-1]:
@@ -513,8 +687,18 @@ class YumOutput:
 
     def simpleList(self, pkg, ui_overflow=False, indent='', highlight=False,
                    columns=None):
-        """ Simple to use function to print a pkg as a line. """
-
+        """Print a package as a line.
+
+        :param pkg: the package to be printed
+        :param ui_overflow: unused
+        :param indent: string to be prefixed onto the line to provide
+           e.g. an indent
+        :param highlight: highlighting options for the name of the
+           package
+        :param colums: tuple containing the space allocated for each
+           column of output.  The columns are the package name, version,
+           and repository
+        """
         if columns is None:
             columns = (-40, -22, -16) # Old default
         ver = pkg.printVer()
@@ -526,9 +710,19 @@ class YumOutput:
 
     def simpleEnvraList(self, pkg, ui_overflow=False,
                         indent='', highlight=False, columns=None):
-        """ Simple to use function to print a pkg as a line, with the pkg
-            itself in envra format so it can be pased to list/install/etc. """
-
+        """Print a package as a line, with the package itself in envra
+        format so it can be passed to list/install/etc. 
+
+        :param pkg: the package to be printed
+        :param ui_overflow: unused
+        :param indent: string to be prefixed onto the line to provide
+           e.g. an indent
+        :param highlight: highlighting options for the name of the
+           package
+        :param colums: tuple containing the space allocated for each
+           column of output.  The columns the are the package envra and
+           repository
+        """
         if columns is None:
             columns = (-63, -16) # Old default
         envra = '%s%s' % (indent, str(pkg))
@@ -538,7 +732,13 @@ class YumOutput:
         print self.fmtColumns(columns, text_width=len)
 
     def fmtKeyValFill(self, key, val):
-        """ Return a key value pair in the common two column output format. """
+        """Return a key value pair in the common two column output
+        format.
+
+        :param key: the key to be formatted
+        :param val: the value associated with *key*
+        :return: the key value pair formatted in two columns for output
+        """
         val = to_str(val)
         keylen = utf8_width(key)
         cols = self.term.columns
@@ -553,6 +753,15 @@ class YumOutput:
         return ret
     
     def fmtSection(self, name, fill='='):
+        """Format and return a section header.  The format of the
+        header is a line with *name* centred, and *fill* repeated on
+        either side to fill an entire line on the terminal.
+
+        :param name: the name of the section
+        :param fill: the character to repeat on either side of *name*
+          to fill an entire line.  *fill* must be a single character.
+        :return: a string formatted to be a section header
+        """
         name = to_str(name)
         cols = self.term.columns - 2
         name_len = utf8_width(name)
@@ -577,6 +786,12 @@ class YumOutput:
         return to_unicode(s)
 
     def infoOutput(self, pkg, highlight=False):
+        """Print information about the given package.
+
+        :param pkg: the package to print information about 
+        :param hightlight: highlighting options for the name of the
+           package
+        """
         (hibeg, hiend) = self._highlight(highlight)
         print _("Name        : %s%s%s") % (hibeg, to_unicode(pkg.name), hiend)
         print _("Arch        : %s") % to_unicode(pkg.arch)
@@ -617,9 +832,22 @@ class YumOutput:
         print ""
     
     def updatesObsoletesList(self, uotup, changetype, columns=None):
-        """takes an updates or obsoletes tuple of pkgobjects and
-           returns a simple printed string of the output and a string
-           explaining the relationship between the tuple members"""
+        """Print a simple string that explains the relationship
+        between the members of an update or obsoletes tuple.
+
+        :param uotup: an update or obsoletes tuple.  The first member
+           is the new package, and the second member is the old
+           package
+        :param changetype: a string indicating what the change between
+           the packages is, e.g. 'updates' or 'obsoletes'
+        :param columns: a tuple containing information about how to
+           format the columns of output.  The absolute value of each
+           number in the tuple indicates how much space has been
+           allocated for the corresponding column.  If the number is
+           negative, the text in the column will be left justified,
+           and if it is positive, the text will be right justified.
+           The columns of output are the package name, version, and repository
+        """
         (changePkg, instPkg) = uotup
 
         if columns is not None:
@@ -640,12 +868,44 @@ class YumOutput:
 
     def listPkgs(self, lst, description, outputType, highlight_na={},
                  columns=None, highlight_modes={}):
-        """outputs based on whatever outputType is. Current options:
-           'list' - simple pkg list
-           'info' - similar to rpm -qi output
-           ...also highlight_na can be passed, and we'll highlight
-           pkgs with (names, arch) in that set."""
-
+        """Prints information about the given list of packages.
+
+        :param lst: a list of packages to print information about
+        :param description: string describing what the list of
+           packages contains, e.g. 'Available Packages'
+        :param outputType: The type of information to be printed.
+           Current options::
+           
+              'list' - simple pkg list
+              'info' - similar to rpm -qi output
+        :param highlight_na: a dictionary containing information about
+              packages that should be highlighted in the output.  The
+              dictionary keys are (name, arch) tuples for the package,
+              and the associated values are the package objects
+              themselves.
+        :param columns: a tuple containing information about how to
+           format the columns of output.  The absolute value of each
+           number in the tuple indicates how much space has been
+           allocated for the corresponding column.  If the number is
+           negative, the text in the column will be left justified,
+           and if it is positive, the text will be right justified.
+           The columns of output are the package name, version, and
+           repository
+        :param highlight_modes: dictionary containing information
+              about to highlight the packages in *highlight_na*.
+              *highlight_modes* should contain the following keys::
+                 
+                 'not_in' - highlighting used for packages not in *highlight_na*
+                 '=' - highlighting used when the package versions are equal
+                 '<' - highlighting used when the package has a lower version number
+                 '>' - highlighting used when the package has a higher version number
+        :return: (exit_code, [errors])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+        """
         if outputType in ['list', 'info']:
             thingslisted = 0
             if len(lst) > 0:
@@ -679,8 +939,11 @@ class YumOutput:
     
         
     def userconfirm(self):
-        """gets a yes or no from the user, defaults to No"""
+        """Get a yes or no from the user, and default to No
 
+        :return: True if the user selects yes, and False if the user
+           selects no
+        """
         yui = (to_unicode(_('y')), to_unicode(_('yes')))
         nui = (to_unicode(_('n')), to_unicode(_('no')))
         aui = (yui[0], yui[1], nui[0], nui[1])
@@ -774,6 +1037,10 @@ class YumOutput:
                                          columns=columns)
     
     def displayPkgsInGroups(self, group):
+        """Output information about the packages in a given group
+        
+        :param group: a Group object to output information about
+        """
         print _('\nGroup: %s') % group.ui_name
 
         verb = self.verbose_logger.isEnabledFor(logginglevels.DEBUG_3)
@@ -807,8 +1074,11 @@ class YumOutput:
                                            columns=columns)
 
     def depListOutput(self, results):
-        """take a list of findDeps results and 'pretty print' the output"""
-        
+        """Format and output a list of findDeps results
+
+        :param results: a list of package dependency information as
+           returned by findDeps
+        """
         verb = self.verbose_logger.isEnabledFor(logginglevels.DEBUG_3)
         for pkg in sorted(results):
             print _("package: %s") % pkg.compactPrint()
@@ -832,7 +1102,18 @@ class YumOutput:
                     print "   provider: %s" % po.compactPrint()
 
     def format_number(self, number, SI=0, space=' '):
-        """Turn numbers into human-readable metric-like numbers"""
+        """Return a human-readable metric-like string representation
+        of a number.
+
+        :param number: the number to be converted to a human-readable form
+        :param SI: If is 0, this function will use the convention
+           that 1 kilobyte = 1024 bytes, otherwise, the convention
+           that 1 kilobyte = 1000 bytes will be used
+        :param space: string that will be placed between the number
+           and the SI prefix
+        :return: a human-readable metric-like string representation of
+           *number*
+        """
         symbols = [ ' ', # (none)
                     'k', # kilo
                     'M', # mega
@@ -870,16 +1151,31 @@ class YumOutput:
 
     @staticmethod
     def format_time(seconds, use_hours=0):
+        """Return a human-readable string representation of a number
+        of seconds.  The string will show seconds, minutes, and
+        optionally hours.
+
+        :param seconds: the number of seconds to convert to a
+           human-readable form
+        :param use_hours: If use_hours is 0, the representation will
+           be in minutes and seconds. Otherwise, it will be in hours,
+           minutes, and seconds
+        :return: a human-readable string representation of *seconds*
+        """
         return urlgrabber.progress.format_time(seconds, use_hours)
 
     def matchcallback(self, po, values, matchfor=None, verbose=None,
                       highlight=None):
-        """ Output search/provides type callback matches. po is the pkg object,
-            values are the things in the po that we've matched.
-            If matchfor is passed, all the strings in that list will be
-            highlighted within the output.
-            verbose overrides logginglevel, if passed. """
-
+        """Output search/provides type callback matches.
+
+        :param po: the package object that matched the search
+        :param values: the information associated with *po* that
+           matched the search
+        :param matchfor: a list of strings to be highlighted in the
+           output
+        :param verbose: whether to output extra verbose information
+        :param highlight: highlighting options for the highlighted matches
+        """
         if self.conf.showdupesfromrepos:
             msg = '%s : ' % po
         else:
@@ -935,10 +1231,23 @@ class YumOutput:
         print '\n\n'
 
     def matchcallback_verbose(self, po, values, matchfor=None):
+        """Output search/provides type callback matches.  This will
+        output more information than :func:`matchcallback`.
+
+        :param po: the package object that matched the search
+        :param values: the information associated with *po* that
+           matched the search
+        :param matchfor: a list of strings to be highlighted in the
+           output
+        """
         return self.matchcallback(po, values, matchfor, verbose=True)
         
     def reportDownloadSize(self, packages, installonly=False):
-        """Report the total download size for a set of packages"""
+        """Report the total download size for a set of packages
+        
+        :param packages: a list of package objects
+        :param installonly: whether the transaction consists only of installations
+        """
         totsize = 0
         locsize = 0
         insize  = 0
@@ -982,7 +1291,10 @@ class YumOutput:
                                         self.format_number(insize))
 
     def reportRemoveSize(self, packages):
-        """Report the total size of packages being removed. """
+        """Report the total size of packages being removed.
+
+        :param packages: a list of package objects
+        """
         totsize = 0
         error = False
         for pkg in packages:
@@ -1002,8 +1314,9 @@ class YumOutput:
                                     self.format_number(totsize))
             
     def listTransaction(self):
-        """returns a string rep of the  transaction in an easy-to-read way."""
-        
+        """Return a string representation of the transaction in an
+        easy-to-read format.
+        """
         self.tsInfo.makelists(True, True)
         pkglist_lines = []
         data  = {'n' : {}, 'v' : {}, 'r' : {}}
@@ -1115,6 +1428,12 @@ Transaction Summary
         return ''.join(out)
         
     def postTransactionOutput(self):
+        """Returns a human-readable summary of the results of the
+        transaction.
+        
+        :return: a string containing a human-readable summary of the
+           results of the transaction
+        """
         out = ''
         
         self.tsInfo.makelists()
@@ -1179,9 +1498,9 @@ Transaction Summary
         return out
 
     def setupProgressCallbacks(self):
-        """sets up the progress callbacks and various 
-           output bars based on debug level"""
-
+        """Set up the progress callbacks and various 
+           output bars based on debug level.
+        """
         # if we're below 2 on the debug level we don't need to be outputting
         # progress bars - this is hacky - I'm open to other options
         # One of these is a download
@@ -1216,10 +1535,12 @@ Transaction Summary
         self.dsCallback = dscb
     
     def setupProgessCallbacks(self):
-        # api purposes only to protect the typo
+        """This function is for API purposes only to protect the typo."""
         self.setupProgressCallbacks()
     
     def setupKeyImportCallbacks(self):
+        """Set up callbacks to import and confirm gpg public keys."""
+
         confirm_func = self._cli_confirm_gpg_key_import
         gpg_import_func = self.getKeyForRepo
         gpgca_import_func = self.getCAKeyForRepo
@@ -1233,14 +1554,12 @@ Transaction Summary
             self.repos.gpgca_import_func = gpgca_import_func
 
     def interrupt_callback(self, cbobj):
-        '''Handle CTRL-C's during downloads
-
-        If a CTRL-C occurs a URLGrabError will be raised to push the download
-        onto the next mirror.  
-        
-        If two CTRL-C's occur in quick succession then yum will exit.
+        '''Handle CTRL-C's during downloads.  If a CTRL-C occurs a
+        URLGrabError will be raised to push the download onto the next
+        mirror.  If two CTRL-C's occur in quick succession then yum
+        will exit.
 
-        @param cbobj: urlgrabber callback obj
+        :param cbobj: :class:`urlgrabber.grabber.CallbackObject`
         '''
         delta_exit_chk = 2.0      # Delta between C-c's so we treat as exit
         delta_exit_str = _("two") # Human readable version of above
@@ -1269,6 +1588,14 @@ to exit.
 
     def download_callback_total_cb(self, remote_pkgs, remote_size,
                                    download_start_timestamp):
+        """Outputs summary information about the download process.
+
+        :param remote_pkgs: a list of package objects that were downloaded
+        :param remote_size: the total amount of information that was
+           downloaded, in bytes
+        :param download_start_timestamp: the time when the download
+           process started, in seconds since the epoch
+        """
         if len(remote_pkgs) <= 1:
             return
         if not hasattr(urlgrabber.progress, 'TerminalLine'):
@@ -1434,8 +1761,17 @@ to exit.
         return tids, printall
 
     def historyListCmd(self, extcmds):
-        """ Shows the user a list of data about the history. """
+        """Output a list of information about the history of yum
+        transactions.
+
+        :param extcmds: list of extra command line arguments
+        :return: (exit_code, [errors])
 
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+        """
         tids, printall = self._history_list_transactions(extcmds)
         if tids is None:
             return 1, ['Failed history list']
@@ -1564,6 +1900,16 @@ to exit.
         return old[0]
 
     def historyInfoCmd(self, extcmds):
+        """Output information about a transaction in history
+
+        :param extcmds: list of extra command line arguments
+        :return: (exit_code, [errors])
+
+        exit_code is::
+
+            0 = we're done, exit
+            1 = we've errored, exit with error string
+        """
         def str2int(x):
             try:
                 return int(x)
@@ -1833,6 +2179,13 @@ to exit.
                               'Updated'      : _('Updated'),
                               }
     def historyInfoCmdPkgsAltered(self, old, pats=[]):
+        """Print information about how packages are altered in a transaction.
+
+        :param old: the :class:`history.YumHistoryTransaction` to
+           print information about
+        :param pats: a list of patterns.  Packages that match a patten
+           in *pats* will be highlighted in the output
+        """
         last = None
         #  Note that these don't use _simple_pkg() because we are showing what
         # happened to them in the transaction ... not the difference between the
@@ -1886,6 +2239,10 @@ to exit.
                                         self._hpkg2from_repo(hpkg))
 
     def historySummaryCmd(self, extcmds):
+        """Print a summary of transactions in history.
+
+        :param extcmds: list of extra command line arguments
+        """
         tids, printall = self._history_list_transactions(extcmds)
         if tids is None:
             return 1, ['Failed history info']
@@ -1946,6 +2303,10 @@ to exit.
                              utf8_width_fill(uiacts, 16, 16), count)
 
     def historyAddonInfoCmd(self, extcmds):
+        """Print addon information about transaction in history.
+
+        :param extcmds: list of extra command line arguments
+        """
         tid = None
         if len(extcmds) > 1:
             tid = extcmds[1]
@@ -1991,8 +2352,11 @@ to exit.
             print ''
 
     def historyPackageListCmd(self, extcmds):
-        """ Shows the user a list of data about the history, from the point
-            of a package(s) instead of via. transactions. """
+        """Print a list of information about transactions from history
+        that involve the given package or packages.
+
+        :param extcmds: list of extra command line arguments
+        """
         tids = self.history.search(extcmds)
         limit = None
         if extcmds and not tids:
@@ -2080,7 +2444,7 @@ to exit.
 
 
 class DepSolveProgressCallBack:
-    """provides text output callback functions for Dependency Solver callback"""
+    """A class to provide text output callback functions for Dependency Solver callback."""
     
     def __init__(self, ayum=None):
         """requires yum-cli log and errorlog functions as arguments"""
@@ -2089,6 +2453,25 @@ class DepSolveProgressCallBack:
         self.ayum = ayum
 
     def pkgAdded(self, pkgtup, mode):
+        """Print information about a package being added to the
+        transaction set.
+
+        :param pkgtup: tuple containing the package name, arch,
+           version, and repository
+        :param mode: a short string indicating why the package is
+           being added to the transaction set.
+
+        Valid current values for *mode* are::
+        
+           i = the package will be installed
+           u = the package will be an update
+           e = the package will be erased
+           r = the package will be reinstalled
+           d = the package will be a downgrade
+           o = the package will be obsoleting another package
+           ud = the package will be updated
+           od = the package will be obsoleted
+        """
         modedict = { 'i': _('installed'),
                      'u': _('an update'),
                      'e': _('erased'),
@@ -2104,43 +2487,85 @@ class DepSolveProgressCallBack:
             modeterm)
         
     def start(self):
+        """Perform setup at the beginning of the dependency solving
+        process.
+        """
         self.loops += 1
         
     def tscheck(self):
+        """Output a message stating that a transaction check is beginning."""
         self.verbose_logger.log(logginglevels.INFO_2, _('--> Running transaction check'))
         
     def restartLoop(self):
+        """Output a message stating that dependency resolution is restarting."""
         self.loops += 1
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Restarting Dependency Resolution with new changes.'))
         self.verbose_logger.debug('---> Loop Number: %d', self.loops)
     
     def end(self):
+        """Output a message stating that dependency resolution has finished."""
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Finished Dependency Resolution'))
 
     
     def procReq(self, name, formatted_req):
+        """Output a message stating that the package *formatted_req*
+        is being processed as a dependency for the package *name*.
+
+        :param name: the name of the package that *formatted_req* is a
+           dependency of
+        :param formatted_req: a string representing the package that
+           is being processed as a dependency of *name*
+        """
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Processing Dependency: %s for package: %s'), formatted_req,
             name)
 
     def procReqPo(self, po, formatted_req):
+        """Output a message stating that the package *formatted_req*
+        is being processed as a dependency for the package *po*.
+
+        :param po: the package object that *formatted_req* is a
+           dependency of
+        :param formatted_req: a string representing the package that
+           is being processed as a dependency of *po*
+        """
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Processing Dependency: %s for package: %s'), formatted_req,
             po)
     
     def groupRemoveReq(self, po, hits):
+        """Output a message stating that the given package will not be
+        removed. This method is used during leaf-only group remove
+        commands to indicate that the package will be kept.
+
+        :param po: the :class:`yum.packages.PackageObject` that will
+           not be removed
+        :param hits: unused
+        """
         self.verbose_logger.log(logginglevels.INFO_2,
             _('---> Keeping package: %s'), po)
 
     def unresolved(self, msg):
+        """Output a message stating that there is an unresolved
+        dependency.
+
+        :param msg: string giving information about the unresolved
+        dependency
+        """
         self.verbose_logger.log(logginglevels.INFO_2, _('--> Unresolved Dependency: %s'),
             msg)
 
     def format_missing_requires(self, reqPo, reqTup):
-        """ Create a message for errorlist, non-cli users could also store this
-            data somewhere and not print errorlist. """
+        """Return an error message stating that a package required to
+        fulfill a dependency is missing.
+
+        :param reqPo: the package object that has a dependency that
+           cannot be fulfilled
+        :param reqTup: the name, flags, and version of the package
+           needed to fulfil the dependency
+        """
         needname, needflags, needversion = reqTup
 
         yb = self.ayum
@@ -2225,45 +2650,89 @@ class DepSolveProgressCallBack:
         return msg
     
     def procConflict(self, name, confname):
+        """Print a message stating that two packages in the
+        transaction conflict.
+
+        :param name: the name of the first package involved in the
+           conflict 
+        :param confname: the name of the second package involved in
+           the conflict
+        """
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Processing Conflict: %s conflicts %s'),
                                 name, confname)
 
     def procConflictPo(self, po, confname):
+        """Print a message stating that two packages in the
+        transaction conflict.
+
+        :param name: the first package object involved in the
+           conflict 
+        :param confname: the second package object involved in
+           the conflict
+        """
         self.verbose_logger.log(logginglevels.INFO_2,
             _('--> Processing Conflict: %s conflicts %s'),
                                 po, confname)
 
     def transactionPopulation(self):
+        """Output a message stating that the transaction set is being populated."""
+
         self.verbose_logger.log(logginglevels.INFO_2, _('--> Populating transaction set '
             'with selected packages. Please wait.'))
     
     def downloadHeader(self, name):
+        """Output a message stating that the header for the given
+        package is being downloaded.
+
+        :param name: the name of the package
+        """
         self.verbose_logger.log(logginglevels.INFO_2, _('---> Downloading header for %s '
             'to pack into transaction set.'), name)
        
 
 class CacheProgressCallback:
+    """A class to handle text output callbacks during metadata cache updates."""
 
-    '''
-    The class handles text output callbacks during metadata cache updates.
-    '''
-    
     def __init__(self):
         self.logger = logging.getLogger("yum.cli")
         self.verbose_logger = logging.getLogger("yum.verbose.cli")
         self.file_logger = logging.getLogger("yum.filelogging.cli")
 
     def log(self, level, message):
+        """Output a log message.
+
+        :param level: the logging level for the message
+        :param message: the message
+        """
         self.verbose_logger.log(level, message)
 
     def errorlog(self, level, message):
+        """Output an errorlog message.
+
+        :param level: the logging level for the message
+        :param message: the message
+        """
         self.logger.log(level, message)
 
     def filelog(self, level, message):
+        """Output a file log message.
+
+        :param level: the logging level for the message
+        :param message: the message
+        """
         self.file_logger.log(level, message)
 
     def progressbar(self, current, total, name=None):
+        """Output the current status to the terminal using a progress
+        status bar.
+
+        :param current: a number representing the amount of work
+           already done
+        :param total: a number representing the total amount of work
+           to be done
+        :param name: a name to label the progress bar with
+        """
         progressbar(current, total, name)
 
 def _pkgname_ui(ayum, pkgname, ts_states=None):
@@ -2316,10 +2785,7 @@ def _pkgname_ui(ayum, pkgname, ts_states=None):
     return pkgname
 
 class YumCliRPMCallBack(RPMBaseCallback):
-
-    """
-    Yum specific callback class for RPM operations.
-    """
+    """A Yum specific callback class for RPM operations."""
 
     width = property(lambda x: _term_width())
 
@@ -2337,11 +2803,31 @@ class YumCliRPMCallBack(RPMBaseCallback):
     #  Installing things have pkg objects passed to the events, so only need to
     # lookup for erased/obsoleted.
     def pkgname_ui(self, pkgname, ts_states=('e', 'od', 'ud', None)):
-        """ Get more information on a simple pkgname, if we can. """
+        """Return more information on a simple pkgname, if possible.
+
+        :param pkgname: the name of the package to find information about
+        :param ts_states: a tuple containing the states where the
+           package might be found
+        """
         return _pkgname_ui(self.ayum, pkgname, ts_states)
 
     def event(self, package, action, te_current, te_total, ts_current, ts_total):
-        # this is where a progress bar would be called
+        """Output information about an rpm operation.  This may
+        include a text progress bar.
+
+        :param package: the package involved in the event
+        :param action: the type of action that is taking place.  Valid
+           values are given by
+           :func:`rpmtrans.RPMBaseCallback.action.keys()`
+        :param te_current: a number representing the amount of work
+           already done in the current transaction
+        :param te_total: a number representing the total amount of work
+           to be done in the current transaction
+        :param ts_current: the number of the current transaction in
+           transaction set
+        :param ts_total: the total number of transactions in the
+           transaction set
+        """
         process = self.action[action]
 
         if not hasattr(self, '_max_action_wid'):
@@ -2378,6 +2864,11 @@ class YumCliRPMCallBack(RPMBaseCallback):
                 print " "
 
     def scriptout(self, package, msgs):
+        """Print messages originating from a package script.
+
+        :param package: unused
+        :param msgs: the messages coming from the script
+        """
         if msgs:
             sys.stdout.write(to_unicode(msgs))
             sys.stdout.flush()
@@ -2432,6 +2923,15 @@ class YumCliRPMCallBack(RPMBaseCallback):
 
 
 def progressbar(current, total, name=None):
+    """Output the current status to the terminal using a simple
+    text progress bar consisting of 50 # marks.
+
+    :param current: a number representing the amount of work
+       already done
+    :param total: a number representing the total amount of work
+       to be done
+    :param name: a name to label the progress bar with
+    """
     """simple progress bar 50 # marks"""
     
     mark = '#'


More information about the Yum-commits mailing list