[Yum-devel] [PATCH] Adds documentation for the output module.

Nick Jacek njacek at redhat.com
Fri Jul 15 14:07:05 UTC 2011


I fixed up the issues you pointed out.

---
 output.py |  650 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 575 insertions(+), 75 deletions(-)

diff --git a/output.py b/output.py
index c146abf..ab2dec1 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'):
@@ -2377,6 +2863,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()
@@ -2431,6 +2922,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 = '#'
-- 
1.7.5.4

---
Nick Jacek

----- Original Message -----
From: "James Antill" <james at fedoraproject.org>
To: "yum development" <yum-devel at lists.baseurl.org>
Sent: Monday, 11 July, 2011 9:28:57 AM
Subject: Re: [Yum-devel] [PATCH] Adds documentation for the output module.

On Fri, 2011-07-08 at 16:44 -0400, Nick Jacek wrote:
> ---
>  output.py |  651 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
>  1 files changed, 576 insertions(+), 75 deletions(-)
[...]
> @@ -473,10 +637,21 @@ 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. 
> +
> +vvvvvvvvvvvvvvvvvvvvf        
> +        :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
> +        """

 The V's have attacked! ;)

[...]
>      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 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
> +        """

 Should probably say "current" values ... and/or see transactioninfo
etc. (although we should be updating it now ;).

_______________________________________________
Yum-devel mailing list
Yum-devel at lists.baseurl.org
http://lists.baseurl.org/mailman/listinfo/yum-devel


More information about the Yum-devel mailing list