Changes between Version 2 and Version 3 of WritingYumPlugins

Show
Ignore:
Author:
skvidal (IP: 24.211.246.61)
Timestamp:
10/23/08 07:06:43 (10 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WritingYumPlugins

    v2 v3  
    3030Registration of hook functions is automatic. The plugin module is inspected for functions named {{{ <slotname>_hook }}}. If a function matching a valid slot name is found then that function is automatically registered as a hook function. 
    3131 
    32 Hook functions all take one argument, for a {{{conduit}}} instance. Conduits are explained below. 
     32Hook functions all take one argument, for a {{{ conduit }}} instance. Conduits are explained below. 
    3333 
    3434The following slots exist: 
    9090An object known as a conduit is passed into hook functions when they are called. This object provides methods and attributes that should be used for all interaction that the plugin has with the rest of Yum.  
    9191 
    92 The conduit varies depending on the plugin slot. Different methods and attributes are available as appropriate for the slot. See the {{{yum.plugins.SLOT_TO_CONDUIT}}} dictionary for details on the conduit class used for a particular slot.  All conduits are subclassed from the {{{PluginConduit}}} class. 
     92The conduit varies depending on the plugin slot. Different methods and attributes are available as appropriate for the slot. See the {{{ yum.plugins.SLOT_TO_CONDUIT }}} dictionary for details on the conduit class used for a particular slot.  All conduits are subclassed from the {{{ PluginConduit }}} class. 
    9393 
    9494== API Dependencies == 
    95 The plugin API and general Yum API are subject to change. For this reason, plugins must state which API they were written for via the {{{requires_api_version}}} attribute. Yum will exit with a useful error if it tries to load the plugin which is not compatible with its API version. 
    96  
    97 In general, a plugin author should set {{{requires_api_version}}} to the API version at the time that the plugin is written. The current API version can be found at {{{yum.plugins.API_VERSION}}}.  
    98  
    99 The {{{yum.plugins}}} module documents how the API version is incremented and the rules for compatibility tests. 
     95The plugin API and general Yum API are subject to change. For this reason, plugins must state which API they were written for via the {{{ requires_api_version }}} attribute. Yum will exit with a useful error if it tries to load the plugin which is not compatible with its API version. 
     96 
     97In general, a plugin author should set {{{ requires_api_version }}} to the API version at the time that the plugin is written. The current API version can be found at {{{ yum.plugins.API_VERSION }}}.  
     98 
     99The {{{ yum.plugins }}} module documents how the API version is incremented and the rules for compatibility tests. 
    100100 
    101101== Plugin Types == 
    102 Plugins must advertise what type of plugin they are via the {{{plugin_type}}} tuple. The advertised type(s) can be used by software using the Yum libraries to control the types of plugins that will be loaded. Yum itself will always load all types of plugins. 
     102Plugins must advertise what type of plugin they are via the {{{ plugin_type }}} tuple. The advertised type(s) can be used by software using the Yum libraries to control the types of plugins that will be loaded. Yum itself will always load all types of plugins. 
    103103 
    104104A plugin may have more than one type. Two plugin types currently exist.  
    119119 
    120120== Stopping Yum == 
    121 A plugin may stop Yum's execution at any point by raising the {{{yum.plugins.PluginYumExit}}} exception. The argument of the exception will be displayed to the user as Yum terminates. 
     121A plugin may stop Yum's execution at any point by raising the {{{ yum.plugins.PluginYumExit }}} exception. The argument of the exception will be displayed to the user as Yum terminates. 
    122122 
    123123== Reading Private Plugin Options == 
    124 Each plugin has its own configuration file in {{{/etc/yum/pluginconf.d/}}}. These configuration files follow standard INI file conventions like Yum's own configuration files. Arbitrary options can be read from a plugin's configuration file at any time by using the following methods. These are available on any conduit instance: 
    125  
    126 {{{#!python numbering=off 
     124Each plugin has its own configuration file in {{{ /etc/yum/pluginconf.d/ }}}. These configuration files follow standard INI file conventions like Yum's own configuration files. Arbitrary options can be read from a plugin's configuration file at any time by using the following methods. These are available on any conduit instance: 
     125 
     126{{{ 
     127    #!python numbering=off 
    127128    def confString(self, section, opt, default=None) 
    128129 
    134135}}} 
    135136 
    136 If the option is missing from the configuration file then the default value passed to method will be returned. See {{{yum.plugins}}} for more documentation on these methods and see the {{{yum(8)}}} and {{{yum.conf(5)}}} man pages for general information on plugin configuration files. 
     137If the option is missing from the configuration file then the default value passed to method will be returned. See {{{ yum.plugins }}} for more documentation on these methods and see the {{{ yum(8) }}} and {{{ yum.conf(5) }}} man pages for general information on plugin configuration files. 
    137138 
    138139== Extending Yum's Configuration Options == 
    140141In addition to having their own configuration file, plugins may modify the 
    141142options available in Yum's own configuration files. A plugin can add new 
    142 options or modify the existing options by modifying the {{{YumConf}}} and 
    143 {{{RepoConf}}} classes defined in {{{yum.config}}}.  
    144  
    145 The {{{YumConf}}} class defines options that are available in the {{{[main]}}} 
    146 section of {{{yum.conf}}}. The {{{RepoConf}}} class defines options that are 
     143options or modify the existing options by modifying the {{{ YumConf }}} and 
     144{{{ RepoConf }}} classes defined in {{{ yum.config }}}.  
     145 
     146The {{{ YumConf }}} class defines options that are available in the {{{ [main] }}} 
     147section of {{{ yum.conf }}}. The {{{ RepoConf }}} class defines options that are 
    147148available in each repository sections of Yum's configuration file(s). 
    148 Modifications to {{{YumConf}}} and {{{RepoConf}}} should occur in the {{{config}}} 
     149Modifications to {{{ YumConf }}} and {{{ RepoConf }}} should occur in the {{{ config }}} 
    149150slot. 
    150151 
    152153files. 
    153154 
    154 {{{#!python numbering=off 
     155{{{ 
     156#!python numbering=off 
    155157from yum import config 
    156158from yum.plugins import TYPE_INTERACTIVE 
    187189}}} 
    188190 
    189 Note how different types of options are defined ({{{IntOption}}}, {{{UrlOption}}}, 
    190 {{{BoolOption}}}). A wide variety of option types are available in 
    191 {{{yum.config}}}. It is even possible for plugins to define their own option 
    192 types by subclassing {{{Option}}} if the existing types aren't sufficient. See 
    193 the source code for the {{{yum.config}}} module for further details. 
     191Note how different types of options are defined ({{{ IntOption }}}, {{{ UrlOption }}}, 
     192{{{ BoolOption }}}). A wide variety of option types are available in 
     193{{{ yum.config }}}. It is even possible for plugins to define their own option 
     194types by subclassing {{{ Option }}} if the existing types aren't sufficient. See 
     195the source code for the {{{ yum.config }}} module for further details. 
    194196 
    195197== Extending Yum's Configuration Options (pre Yum 2.9.x, deprecated) == 
    196 In addition to having their own configuration file, plugins may add extra options to Yum's main configuration files. A plugin must register new options in the {{{config}}} slot using the {{{registerOpt()}}} conduit method: 
    197 {{{#!python numbering=off 
     198In addition to having their own configuration file, plugins may add extra options to Yum's main configuration files. A plugin must register new options in the {{{ config }}} slot using the {{{ registerOpt() }}} conduit method: 
     199{{{ 
     200#!python numbering=off 
    198201    registerOpt(name, valuetype, where, default) 
    199202}}} 
    220223    The default value returned for the option if it isn't present. 
    221224}}} 
    222 The option values defined in the {{{[main]}}} section may be read by calling the 
    223 {{{getConf()}}} repository method. The options will be available as attributes of the returned object. 
    224  
    225 New repository options will be available as attributes of the repository objects returned via the {{{getRepos()}}} conduit method. 
     225The option values defined in the {{{ [main] }}} section may be read by calling the 
     226{{{ getConf() }}} repository method. The options will be available as attributes of the returned object. 
     227 
     228New repository options will be available as attributes of the repository objects returned via the {{{ getRepos() }}} conduit method. 
    226229 
    227230The following example plugin shows how a custom option may be defined and 
    228231read: 
    229 {{{#!python numbering=off 
     232{{{ 
     233#!python numbering=off 
    230234    from yum.constants import * 
    231235    from yum.plugins import TYPE_INTERACTIVE 
    247251== Extending Yum's Command Line Options == 
    248252A plugin may add extra command line options to Yum. To do this the plugin 
    249 should call the {{{getOptParser()}}} conduit method during the {{{config}}} or 
    250 {{{init}}} slot. This will return an {{{OptionParser}}} instance which the plugin 
    251 may modify.  See the Python standard library {{{optparse}}} module documentation for information on how to manipulate this object. 
    252  
    253 The parsed command line options may be read in any slot after the {{{init}}} 
    254 slot. The values returned are as for {{{OptionParser.parse_args()}}}. 
     253should call the {{{ getOptParser() }}} conduit method during the {{{ config }}} or 
     254{{{ init }}} slot. This will return an {{{ OptionParser }}} instance which the plugin 
     255may modify.  See the Python standard library {{{ optparse }}} module documentation for information on how to manipulate this object. 
     256 
     257The parsed command line options may be read in any slot after the {{{ init }}} 
     258slot. The values returned are as for {{{ OptionParser.parse_args() }}}. 
    255259 
    256260Options added by plugins will show up in Yum's command line help output (ie. 
    257 {{{yum --help}}}) 
    258  
    259 The following plugin demonstrates the addition of new command line options by adding a {{{--downloadonly}}} option: 
    260 {{{#!python numbering=off 
     261{{{ yum --help }}}) 
     262 
     263The following plugin demonstrates the addition of new command line options by adding a {{{ --downloadonly }}} option: 
     264{{{ 
     265#!python numbering=off 
    261266    from yum.plugins import PluginYumExit, TYPE_INTERACTIVE 
    262267 
    279284The easiest way to get started writing Yum plugins is to look at some examples. 
    280285The yum-utils package contains a number of useful plugins which will act as a 
    281 useful starting point. The yum-utils git tree can be viewed here: [http://devel.linux.duke.edu/gitweb/?p=yum-utils.git;a=tree] 
     286useful starting point. The yum-utils git tree can be viewed here: [http://yum.baseurl.org/gitweb/?p=yum-utils.git;a=tree] 
    282287---- 
    283288