[yum-commits] Branch 'yum-3_2_X' - yum/plugins.py

James Antill james at osuosl.org
Mon Aug 15 16:26:05 UTC 2011


 yum/plugins.py |  293 ++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 199 insertions(+), 94 deletions(-)

New commits:
commit c7cb72222ea9325ca7cc5e3e7afd8b8ad1b67d4c
Author: Nick Jacek <njacek at redhat.com>
Date:   Fri Aug 12 16:02:12 2011 -0400

    Adds and modifies documentation for the yum.plugins module.

diff --git a/yum/plugins.py b/yum/plugins.py
index bfc49b7..9ddcae6 100644
--- a/yum/plugins.py
+++ b/yum/plugins.py
@@ -66,9 +66,9 @@ from yum.i18n import utf8_width
 API_VERSION = '2.6'
 
 class DeprecatedInt(int):
-    '''
-    A simple int subclass that used to check when a deprecated constant is used.
-    '''
+    """A simple int subclass that is used to check when a deprecated
+    constant is used.
+    """
 
 # Plugin types
 TYPE_CORE = 0
@@ -105,8 +105,8 @@ SLOT_TO_CONDUIT = {
 SLOTS = sorted(SLOT_TO_CONDUIT.keys())
 
 class PluginYumExit(Exception):
-    '''Used by plugins to signal that yum should stop
-    '''
+    """Exception that can be raised by plugins to signal that yum should stop."""
+
     def __init__(self, value="", translation_domain=""):
         self.value = value
         self.translation_domain = translation_domain
@@ -117,9 +117,7 @@ class PluginYumExit(Exception):
             return self.value
     
 class YumPlugins:
-    '''
-    Manager class for Yum plugins.
-    '''
+    """Manager class for Yum plugins."""
 
     def __init__(self, base, searchpath, optparser=None, types=None, 
             pluginconfpath=None,disabled=None,enabled=None):
@@ -167,8 +165,13 @@ class YumPlugins:
         self.run('config')
 
     def run(self, slotname, **kwargs):
-        '''Run all plugin functions for the given slot.
-        '''
+        """Run all plugin functions for the given slot.
+
+        :param slotname: a string representing the name of the slot to
+           run the plugins for
+        :param kwargs: keyword arguments that will be simply passed on
+           to the plugins
+        """
         # Determine handler class to use
         conduitcls = SLOT_TO_CONDUIT.get(slotname, None)
         if conduitcls is None:
@@ -356,23 +359,35 @@ class YumPlugins:
         return parser
 
     def setCmdLine(self, opts, commands):
-        '''Set the parsed command line options so that plugins can access them
-        '''
+        """Set the parsed command line options so that plugins can
+        access them.
+
+        :param opts: a dictionary containing the values of the command
+           line options
+        :param commands: a list of command line arguments passed to yum
+        """
         self.cmdline = (opts, commands)
 
 
 class DummyYumPlugins:
-    '''
-    This class provides basic emulation of the YumPlugins class. It exists so
-    that calls to plugins.run() don't fail if plugins aren't in use.
-    '''
+    """This class provides basic emulation of the :class:`YumPlugins`
+    class. It exists so that calls to plugins.run() don't fail if
+    plugins aren't in use.
+    """
     def run(self, *args, **kwargs):
+        """Do nothing.  All arguments are unused."""
+
         pass
 
     def setCmdLine(self, *args, **kwargs):
+        """Do nothing.  All arguments are unused."""
+
         pass
 
 class PluginConduit:
+    """A conduit class to transfer information between yum and the
+    plugin.
+    """
     def __init__(self, parent, base, conf):
         self._parent = parent
         self._base = base
@@ -382,14 +397,30 @@ class PluginConduit:
         self.verbose_logger = logging.getLogger("yum.verbose.plugin")
 
     def info(self, level, msg):
+        """Send an info message to the logger.
+
+        :param level: the level of the message to send
+        :param msg: the message to send
+        """
         converted_level = logginglevels.logLevelFromDebugLevel(level)
         self.verbose_logger.log(converted_level, msg)
 
     def error(self, level, msg):
+        """Send an error message to the logger.
+
+        :param level: the level of the message to send
+        :param msg: the message to send
+        """
         converted_level = logginglevels.logLevelFromErrorLevel(level)
         self.logger.log(converted_level, msg)
 
     def promptYN(self, msg):
+        """Return a yes or no response, either from assumeyes already
+        being set, or from prompting the user.
+
+        :param msg: the message to prompt the user with
+        :return: 1 if the response is yes, and 0 if the response is no
+        """
         self.info(2, msg)
         if self._base.conf.assumeyes:
             return 1
@@ -397,88 +428,96 @@ class PluginConduit:
             return self._base.userconfirm()
 
     def getYumVersion(self):
+        """Return a string representing the current version of yum."""
+
         import yum
         return yum.__version__
 
     def getOptParser(self):
-        '''Return the optparse.OptionParser instance for this execution of Yum
-
-        In the "config" and "init" slots a plugin may add extra options to this
-        instance to extend the command line options that Yum exposes.
-
-        In all other slots a plugin may only read the OptionParser instance.
-        Any modification of the instance at this point will have no effect. 
-        
-        See the getCmdLine() method for details on how to retrieve the parsed
-        values of command line options.
-
-        @return: the global optparse.OptionParser instance used by Yum. May be
-            None if an OptionParser isn't in use.
-        '''
+        """Return the :class:`optparse.OptionParser` instance for this
+        execution of Yum.  In the "config" and "init" slots a plugin
+        may add extra options to this instance to extend the command
+        line options that Yum exposes.  In all other slots a plugin
+        may only read the :class:`OptionParser` instance.  Any
+        modification of the instance at this point will have no
+        effect.  See the
+        :func:`PreRepoSetupPluginConduit.getCmdLine` method for
+        details on how to retrieve the parsed values of command line
+        options.
+
+        :return: the global :class:`optparse.OptionParser` instance used by
+           Yum. May be None if an OptionParser isn't in use
+        """
         # ' xemacs highlighting hack
         # This isn't API compatible :(
         # return self._parent.optparser.plugin_option_group
         return self._parent.optparser
 
     def confString(self, section, opt, default=None):
-        '''Read a string value from the plugin's own configuration file
+        """Read a string value from the plugin's own configuration file.
 
-        @param section: Configuration file section to read.
-        @param opt: Option name to read.
-        @param default: Value to read if option is missing.
-        @return: String option value read, or default if option was missing.
-        '''
+        :param section: configuration file section to read
+        :param opt: option name to read
+        :param default: value to read if the option is missing
+        :return: string option value read, or default if option was missing
+        """
         # ' xemacs highlighting hack
         return config.getOption(self._conf, section, opt, config.Option(default))
 
     def confInt(self, section, opt, default=None):
-        '''Read an integer value from the plugin's own configuration file
+        """Read an integer value from the plugin's own configuration file.
 
-        @param section: Configuration file section to read.
-        @param opt: Option name to read.
-        @param default: Value to read if option is missing.
-        @return: Integer option value read, or default if option was missing or
-            could not be parsed.
-        '''
+        :param section: configuration file section to read
+        :param opt: option name to read
+        :param default: value to read if the option is missing
+
+        :return: the integer option value read, or *default* if the
+            option was missing or could not be parsed
+        """
         return config.getOption(self._conf, section, opt, config.IntOption(default))
 
     def confFloat(self, section, opt, default=None):
-        '''Read a float value from the plugin's own configuration file
-
-        @param section: Configuration file section to read.
-        @param opt: Option name to read.
-        @param default: Value to read if option is missing.
-        @return: Float option value read, or default if option was missing or
-            could not be parsed.
-        '''
+        """Read a float value from the plugin's own configuration file.
+
+        :param section: configuration file section to read
+        :param opt: option name to read
+        :param default: value to read if the option is missing
+        :return: float option value read, or *default* if the option was
+            missing or could not be parsed
+        """
         return config.getOption(self._conf, section, opt, config.FloatOption(default))
 
     def confBool(self, section, opt, default=None):
-        '''Read a boolean value from the plugin's own configuration file
-
-        @param section: Configuration file section to read.
-        @param opt: Option name to read.
-        @param default: Value to read if option is missing.
-        @return: Boolean option value read, or default if option was missing or
-            could not be parsed.
-        '''
+        """Read a boolean value from the plugin's own configuration file
+
+        :param section: configuration file section to read
+        :param opt: option name to read
+        :param default: value to read if the option is missing
+        :return: boolean option value read, or *default* if the option
+            was missing or could not be parsed
+        """
         return config.getOption(self._conf, section, opt, config.BoolOption(default))
 
     def registerPackageName(self, name):
+        """Register the name of a package to use.
+
+        :param name: the name of the package to register
+        """
         self._base.run_with_package_names.add(name)
 
 
 class ConfigPluginConduit(PluginConduit):
+    """A conduit for use in the config slot."""
 
     def registerOpt(self, name, valuetype, where, default):
-        '''Register a yum configuration file option.
-
-        @param name: Name of the new option.
-        @param valuetype: Option type (PLUG_OPT_BOOL, PLUG_OPT_STRING ...)
-        @param where: Where the option should be available in the config file.
-            (PLUG_OPT_WHERE_MAIN, PLUG_OPT_WHERE_REPO, ...)
-        @param default: Default value for the option if not set by the user.
-        '''
+        """Deprecated.  Register a yum configuration file option.
+
+        :param name: name of the new option
+        :param valuetype: option type (PLUG_OPT_BOOL, PLUG_OPT_STRING, etc.)
+        :param where: where the option should be available in the config file
+            (PLUG_OPT_WHERE_MAIN, PLUG_OPT_WHERE_REPO, etc)
+        :param default: default value for the option if it is not set by the user
+        """
         warnings.warn('registerOpt() will go away in a future version of Yum.\n'
                 'Please manipulate config.YumConf and config.RepoConf directly.',
                 DeprecationWarning)
@@ -502,64 +541,93 @@ class ConfigPluginConduit(PluginConduit):
             setattr(config.RepoConf, name, config.Inherit(option))
 
     def registerCommand(self, command):
+        """Register a new command.
+
+        :param command: the command to register
+        :raises: :class:`yum.Errors.ConfigError` if the registration
+           of commands is not supported
+        """
         if hasattr(self._base, 'registerCommand'):
             self._base.registerCommand(command)
         else:
             raise Errors.ConfigError(_('registration of commands not supported'))
 
 class PostConfigPluginConduit(ConfigPluginConduit):
+    """Conduit for use in the postconfig slot."""
 
     def getConf(self):
+        """Return a dictionary containing the values of the
+        configuration options.
+
+        :return: a dictionary containing the values of the
+           configuration options
+        """
         return self._base.conf
 
 class InitPluginConduit(PluginConduit):
+    """Conduit for use in the init slot."""
 
     def getConf(self):
+        """Return a dictionary containing the values of the
+        configuration options.
+
+        :return: a dictionary containing the values of the
+           configuration options
+        """
         return self._base.conf
 
     def getRepos(self):
-        '''Return Yum's container object for all configured repositories.
+        """Return Yum's container object for all configured repositories.
 
-        @return: Yum's RepoStorage instance
-        '''
+        :return: Yum's :class:`yum.repos.RepoStorage` instance
+        """
         return self._base.repos
 
 class ArgsPluginConduit(InitPluginConduit):
+    """Conduit for dealing with command line arguments."""
 
     def __init__(self, parent, base, conf, args):
         InitPluginConduit.__init__(self, parent, base, conf)
         self._args = args
 
     def getArgs(self):
+        """Return a list of the command line arguments passed to yum.
+
+        :return: a list of the command line arguments passed to yum
+        """
         return self._args
 
 class PreRepoSetupPluginConduit(InitPluginConduit):
+    """Conduit for use in the prererosetup slot."""
+
 
     def getCmdLine(self):
-        '''Return parsed command line options.
+        """Return parsed command line options.
 
-        @return: (options, commands) as returned by OptionParser.parse_args()
-        '''
+        :return: (options, commands) as returned by :class:`OptionParser.parse_args()`
+        """
         return self._parent.cmdline
 
     def getRpmDB(self):
-        '''Return a representation of local RPM database. This allows querying
-        of installed packages.
+        """Return a representation of the local RPM database. This
+        allows querying of installed packages.
 
-        @return: rpmUtils.RpmDBHolder instance
-        '''
+        :return: a :class:`yum.rpmUtils.RpmDBHolder` instance
+        """
         return self._base.rpmdb
 
 class PostRepoSetupPluginConduit(PreRepoSetupPluginConduit):
+    """Conduit for use in the postreposetup slot."""
 
     def getGroups(self):
-        '''Return group information.
+        """Return group information.
 
-        @return: yum.comps.Comps instance
-        '''
+        :return: :class:`yum.comps.Comps` instance
+        """
         return self._base.comps
 
 class DownloadPluginConduit(PostRepoSetupPluginConduit):
+    """Conduit for use in the download slots."""
 
     def __init__(self, parent, base, conf, pkglist, errors=None):
         PostRepoSetupPluginConduit.__init__(self, parent, base, conf)
@@ -567,24 +635,35 @@ class DownloadPluginConduit(PostRepoSetupPluginConduit):
         self._errors = errors
 
     def getDownloadPackages(self):
-        '''Return a list of package objects representing packages to be
+        """Return a list of package objects representing packages to be
         downloaded.
-        '''
+
+        :return: a list of package object representing packages to be
+           downloaded
+        """
         return self._pkglist
 
     def getErrors(self):
-        '''Return a dictionary of download errors. 
+        """Return a dictionary of download errors. 
         
-        The returned dictionary is indexed by package object. Each element is a
-        list of strings describing the error.
-        '''
+        :return: a dictionary of download errors. This dictionary is
+           indexed by package object. Each element is a list of
+           strings describing the error
+        """
         if not self._errors:
             return {}
         return self._errors
 
 class MainPluginConduit(PostRepoSetupPluginConduit):
-
+    """Main conduit class for plugins.  Many other conduit classes
+    will inherit from this class.
+    """
     def getPackages(self, repo=None):
+        """Return a list of packages.
+
+        :param repo: the repo to return a packages from
+        :return: a list of package objects
+        """
         if repo:
             arg = repo.id
         else:
@@ -592,50 +671,76 @@ class MainPluginConduit(PostRepoSetupPluginConduit):
         return self._base.pkgSack.returnPackages(arg)
 
     def getPackageByNevra(self, nevra):
-        '''Retrieve a package object from the packages loaded by Yum using
-        nevra information 
+        """Retrieve a package object from the packages loaded by Yum using
+        nevra information.
         
-        @param nevra: A tuple holding (name, epoch, version, release, arch)
+        :param nevra: a tuple holding (name, epoch, version, release, arch)
             for a package
-        @return: A PackageObject instance (or subclass)
-        '''
+        :return: a :class:`yum.packages.PackageObject` instance (or subclass)
+        """
         return self._base.getPackageObject(nevra)
 
     def delPackage(self, po):
+        """Delete the given package from the package sack.
+
+        :param po: the package object to delete
+        """
         po.repo.sack.delPackage(po)
 
     def getTsInfo(self):
+        """Return transaction set.
+
+        :return: the transaction set
+        """
         return self._base.tsInfo
 
 class DepsolvePluginConduit(MainPluginConduit):
+    """Conduit for use in solving dependencies."""
+
     def __init__(self, parent, base, conf, rescode=None, restring=[]):
         MainPluginConduit.__init__(self, parent, base, conf)
         self.resultcode = rescode
         self.resultstring = restring
 
 class CompareProvidersPluginConduit(MainPluginConduit):
+    """Conduit to compare different providers of packages."""
+
     def __init__(self, parent, base, conf, providers_dict={}, reqpo=None):
         MainPluginConduit.__init__(self, parent, base, conf)
         self.packages = providers_dict
         self.reqpo = reqpo
 
 class HistoryPluginConduit(MainPluginConduit):
+    """Conduit to access information about the yum history."""
+
     def __init__(self, parent, base, conf, rescode=None, restring=[]):
         MainPluginConduit.__init__(self, parent, base, conf)
         self.history = self._base.history
 
 class VerifyPluginConduit(MainPluginConduit):
+    """Conduit to verify packages."""
+
     def __init__(self, parent, base, conf, verify_package):
         MainPluginConduit.__init__(self, parent, base, conf)
         self.verify_package = verify_package
 
 def parsever(apiver):
+    """Parse a string representing an api version.
+
+    :param apiver: a string representing an api version
+    :return: a tuple containing the major and minor version numbers
+    """
     maj, min = apiver.split('.')
     return int(maj), int(min)
 
 def apiverok(a, b):
-    '''Return true if API version "a" supports API version "b"
-    '''
+    """Return true if API version "a" supports API version "b"
+
+    :param a: a string representing an api version
+    :param b: a string representing an api version
+
+    :return: whether version *a* supports version *b*
+    """
     a = parsever(a)
     b = parsever(b)
 


More information about the Yum-commits mailing list