<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>PluginManager — Yapsy 1.10.2 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '1.10.2', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="shortcut icon" href="_static/yapsy-favicon.ico"/> <link rel="top" title="Yapsy 1.10.2 documentation" href="index.html" /> <link rel="next" title="PluginInfo" href="PluginInfo.html" /> <link rel="prev" title="IPlugin" href="IPlugin.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="PluginInfo.html" title="PluginInfo" accesskey="N">next</a> |</li> <li class="right" > <a href="IPlugin.html" title="IPlugin" accesskey="P">previous</a> |</li> <li><a href="index.html">Yapsy 1.10.2 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="pluginmanager"> <h1>PluginManager<a class="headerlink" href="#pluginmanager" title="Permalink to this headline">¶</a></h1> <div class="toctree-wrapper compound"> <ul class="simple"> </ul> </div> <span class="target" id="module-yapsy.PluginManager"></span><div class="section" id="role"> <h2>Role<a class="headerlink" href="#role" title="Permalink to this headline">¶</a></h2> <p>The <tt class="docutils literal"><span class="pre">PluginManager</span></tt> loads plugins that enforce the <a class="reference internal" href="#plugin-description-policy">Plugin Description Policy</a>, and offers the most simple methods to activate and deactivate the plugins once they are loaded.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">It may also classify the plugins in various categories, but this behaviour is optional and if not specified elseway all plugins are stored in the same default category.</p> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">It is often more useful to have the plugin manager behave like singleton, this functionality is provided by <tt class="docutils literal"><span class="pre">PluginManagerSingleton</span></tt></p> </div> </div> <div class="section" id="plugin-description-policy"> <h2>Plugin Description Policy<a class="headerlink" href="#plugin-description-policy" title="Permalink to this headline">¶</a></h2> <p>When creating a <tt class="docutils literal"><span class="pre">PluginManager</span></tt> instance, one should provide it with a list of directories where plugins may be found. In each directory, a plugin should contain the following elements:</p> <p>For a <em>Standard</em> plugin:</p> <blockquote> <div><p><tt class="docutils literal"><span class="pre">myplugin.yapsy-plugin</span></tt></p> <blockquote> <div>A <em>plugin info file</em> identical to the one previously described.</div></blockquote> <p><tt class="docutils literal"><span class="pre">myplugin</span></tt></p> <blockquote> <div>A directory ontaining an actual Python plugin (ie with a <tt class="docutils literal"><span class="pre">__init__.py</span></tt> file that makes it importable). The upper namespace of the plugin should present a class inheriting the <tt class="docutils literal"><span class="pre">IPlugin</span></tt> interface (the same remarks apply here as in the previous case).</div></blockquote> </div></blockquote> <p>For a <em>Single file</em> plugin:</p> <blockquote> <div><p><tt class="docutils literal"><span class="pre">myplugin.yapsy-plugin</span></tt></p> <blockquote> <div><p>A <em>plugin info file</em> which is identified thanks to its extension, see the <a class="reference internal" href="#plugin-info-file-format">Plugin Info File Format</a> to see what should be in this file.</p> <p>The extension is customisable at the <tt class="docutils literal"><span class="pre">PluginManager</span></tt>‘s instanciation, since one may usually prefer the extension to bear the application name.</p> </div></blockquote> <p><tt class="docutils literal"><span class="pre">myplugin.py</span></tt></p> <blockquote> <div>The source of the plugin. This file should at least define a class inheriting the <tt class="docutils literal"><span class="pre">IPlugin</span></tt> interface. This class will be instanciated at plugin loading and it will be notified the activation/deactivation events.</div></blockquote> </div></blockquote> <div class="section" id="plugin-info-file-format"> <h3>Plugin Info File Format<a class="headerlink" href="#plugin-info-file-format" title="Permalink to this headline">¶</a></h3> <p>The plugin info file gathers, as its name suggests, some basic information about the plugin.</p> <ul class="simple"> <li>it gives crucial information needed to be able to load the plugin</li> <li>it provides some documentation like information like the plugin author’s name and a short description fo the plugin functionality.</li> </ul> <p>Here is an example of what such a file should contain:</p> <div class="highlight-python"><pre>[Core] Name = My plugin Name Module = the_name_of_the_pluginto_load_with_no_py_ending [Documentation] Description = What my plugin broadly does Author = My very own name Version = 0.1 Website = My very own website Version = the_version_number_of_the_plugin</pre> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">From such plugin descriptions, the <tt class="docutils literal"><span class="pre">PluginManager</span></tt> will built its own representations of the plugins as instances of the <a class="reference internal" href="PluginInfo.html"><em>PluginInfo</em></a> class.</p> </div> </div> </div> <div class="section" id="changing-the-default-behaviour"> <h2>Changing the default behaviour<a class="headerlink" href="#changing-the-default-behaviour" title="Permalink to this headline">¶</a></h2> <p>The default behaviour for locating and loading plugins can be changed using the various options exposed on the interface via getters.</p> <p>The plugin detection, in particular, can be fully customized by settting a custom plugin locator. See <tt class="docutils literal"><span class="pre">IPluginLocator</span></tt> for more details on this.</p> </div> <div class="section" id="extensibility"> <h2>Extensibility<a class="headerlink" href="#extensibility" title="Permalink to this headline">¶</a></h2> <p>Several mechanisms have been put up to help extending the basic functionalities of the proivided classes.</p> <p>A few <em>hints</em> to help you extend those classes:</p> <p>If the new functionalities do not overlap the ones already implemented, then they should be implemented as a Decorator class of the base plugin. This should be done by inheriting the <tt class="docutils literal"><span class="pre">PluginManagerDecorator</span></tt>.</p> <p>If this previous way is not possible, then the functionalities should be added as a subclass of <tt class="docutils literal"><span class="pre">PluginManager</span></tt>.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The first method is highly prefered since it makes it possible to have a more flexible design where one can pick several functionalities and litterally <em>add</em> them to get an object corresponding to one’s precise needs.</p> </div> </div> <div class="section" id="api"> <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</a></h2> <dl class="class"> <dt id="yapsy.PluginManager.PluginManager"> <em class="property">class </em><tt class="descclassname">yapsy.PluginManager.</tt><tt class="descname">PluginManager</tt><big>(</big><em>categories_filter=None</em>, <em>directories_list=None</em>, <em>plugin_info_ext=None</em>, <em>plugin_locator=None</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager" title="Permalink to this definition">¶</a></dt> <dd><p>Manage several plugins by ordering them in categories.</p> <p>The mechanism for searching and loading the plugins is already implemented in this class so that it can be used directly (hence it can be considered as a bit more than a mere interface)</p> <p>The file describing a plugin must be written in the syntax compatible with Python’s ConfigParser module as in the <a class="reference internal" href="#plugin-info-file-format">Plugin Info File Format</a></p> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.activatePluginByName"> <tt class="descname">activatePluginByName</tt><big>(</big><em>name</em>, <em>category='Default'</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.activatePluginByName" title="Permalink to this definition">¶</a></dt> <dd><p>Activate a plugin corresponding to a given category + name.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.appendPluginCandidate"> <tt class="descname">appendPluginCandidate</tt><big>(</big><em>candidateTuple</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.appendPluginCandidate" title="Permalink to this definition">¶</a></dt> <dd><p>Append a new candidate to the list of plugins that should be loaded.</p> <p>The candidate must be represented by the same tuple described in <tt class="docutils literal"><span class="pre">getPluginCandidates</span></tt>.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.appendPluginToCategory"> <tt class="descname">appendPluginToCategory</tt><big>(</big><em>plugin</em>, <em>category_name</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.appendPluginToCategory" title="Permalink to this definition">¶</a></dt> <dd><p>Append a new plugin to the given category.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.collectPlugins"> <tt class="descname">collectPlugins</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.collectPlugins" title="Permalink to this definition">¶</a></dt> <dd><p>Walk through the plugins’ places and look for plugins. Then for each plugin candidate look for its category, load it and stores it in the appropriate slot of the category_mapping.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.deactivatePluginByName"> <tt class="descname">deactivatePluginByName</tt><big>(</big><em>name</em>, <em>category='Default'</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.deactivatePluginByName" title="Permalink to this definition">¶</a></dt> <dd><p>Desactivate a plugin corresponding to a given category + name.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getAllPlugins"> <tt class="descname">getAllPlugins</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getAllPlugins" title="Permalink to this definition">¶</a></dt> <dd><p>Return the list of all plugins (belonging to all categories).</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getCategories"> <tt class="descname">getCategories</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getCategories" title="Permalink to this definition">¶</a></dt> <dd><p>Return the list of all categories.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getPluginByName"> <tt class="descname">getPluginByName</tt><big>(</big><em>name</em>, <em>category='Default'</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getPluginByName" title="Permalink to this definition">¶</a></dt> <dd><p>Get the plugin correspoding to a given category and name</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getPluginCandidates"> <tt class="descname">getPluginCandidates</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getPluginCandidates" title="Permalink to this definition">¶</a></dt> <dd><p>Return the list of possible plugins.</p> <p>Each possible plugin (ie a candidate) is described by a 3-uple: (info file path, python file path, plugin info instance)</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getPluginInfoClass"> <tt class="descname">getPluginInfoClass</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getPluginInfoClass" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED(>1.9): directly control that with the IPluginLocator instance instead !</p> <p>Get the class that holds PluginInfo.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getPluginLocator"> <tt class="descname">getPluginLocator</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getPluginLocator" title="Permalink to this definition">¶</a></dt> <dd><p>Grant direct access to the plugin locator.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.getPluginsOfCategory"> <tt class="descname">getPluginsOfCategory</tt><big>(</big><em>category_name</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.getPluginsOfCategory" title="Permalink to this definition">¶</a></dt> <dd><p>Return the list of all plugins belonging to a category.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.loadPlugins"> <tt class="descname">loadPlugins</tt><big>(</big><em>callback=None</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.loadPlugins" title="Permalink to this definition">¶</a></dt> <dd><p>Load the candidate plugins that have been identified through a previous call to locatePlugins. For each plugin candidate look for its category, load it and store it in the appropriate slot of the <tt class="docutils literal"><span class="pre">category_mapping</span></tt>.</p> <p>If a callback function is specified, call it before every load attempt. The <tt class="docutils literal"><span class="pre">plugin_info</span></tt> instance is passed as an argument to the callback.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.locatePlugins"> <tt class="descname">locatePlugins</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.locatePlugins" title="Permalink to this definition">¶</a></dt> <dd><p>Convenience method (actually call the IPluginLocator method)</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.removePluginCandidate"> <tt class="descname">removePluginCandidate</tt><big>(</big><em>candidateTuple</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.removePluginCandidate" title="Permalink to this definition">¶</a></dt> <dd><p>Remove a given candidate from the list of plugins that should be loaded.</p> <p>The candidate must be represented by the same tuple described in <tt class="docutils literal"><span class="pre">getPluginCandidates</span></tt>.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.removePluginFromCategory"> <tt class="descname">removePluginFromCategory</tt><big>(</big><em>plugin</em>, <em>category_name</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.removePluginFromCategory" title="Permalink to this definition">¶</a></dt> <dd><p>Remove a plugin from the category where it’s assumed to belong.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.setCategoriesFilter"> <tt class="descname">setCategoriesFilter</tt><big>(</big><em>categories_filter</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.setCategoriesFilter" title="Permalink to this definition">¶</a></dt> <dd><p>Set the categories of plugins to be looked for as well as the way to recognise them.</p> <p>The <tt class="docutils literal"><span class="pre">categories_filter</span></tt> first defines the various categories in which the plugins will be stored via its keys and it also defines the interface tha has to be inherited by the actual plugin class belonging to each category.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.setPluginInfoClass"> <tt class="descname">setPluginInfoClass</tt><big>(</big><em>picls</em>, <em>strategies=None</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.setPluginInfoClass" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED(>1.9): directly configure the IPluginLocator instance instead !</p> <p>Convenience method (actually call self.getPluginLocator().setPluginInfoClass)</p> <p>When using a <tt class="docutils literal"><span class="pre">PluginFileLocator</span></tt> you may restrict the strategies to which the change of PluginInfo class will occur by just giving the list of strategy names in the argument “strategies”</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.setPluginInfoExtension"> <tt class="descname">setPluginInfoExtension</tt><big>(</big><em>ext</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.setPluginInfoExtension" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED(>1.9): for backward compatibility. Directly configure the IPluginLocator instance instead !</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">This will only work if the strategy “info_ext” is active for locating plugins.</p> </div> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.setPluginLocator"> <tt class="descname">setPluginLocator</tt><big>(</big><em>plugin_locator</em>, <em>dir_list=None</em>, <em>picls=None</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.setPluginLocator" title="Permalink to this definition">¶</a></dt> <dd><p>Sets the strategy used to locate the basic information.</p> <p>See <tt class="docutils literal"><span class="pre">IPluginLocator</span></tt> for the policy that plugin_locator must enforce.</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.setPluginPlaces"> <tt class="descname">setPluginPlaces</tt><big>(</big><em>directories_list</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.setPluginPlaces" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED(>1.9): directly configure the IPluginLocator instance instead !</p> <p>Convenience method (actually call the IPluginLocator method)</p> </dd></dl> <dl class="method"> <dt id="yapsy.PluginManager.PluginManager.updatePluginPlaces"> <tt class="descname">updatePluginPlaces</tt><big>(</big><em>directories_list</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManager.updatePluginPlaces" title="Permalink to this definition">¶</a></dt> <dd><p>DEPRECATED(>1.9): directly configure the IPluginLocator instance instead !</p> <p>Convenience method (actually call the IPluginLocator method)</p> </dd></dl> </dd></dl> <dl class="class"> <dt id="yapsy.PluginManager.PluginManagerSingleton"> <em class="property">class </em><tt class="descclassname">yapsy.PluginManager.</tt><tt class="descname">PluginManagerSingleton</tt><a class="headerlink" href="#yapsy.PluginManager.PluginManagerSingleton" title="Permalink to this definition">¶</a></dt> <dd><p>Singleton version of the most basic plugin manager.</p> <p>Being a singleton, this class should not be initialised explicitly and the <tt class="docutils literal"><span class="pre">get</span></tt> classmethod must be called instead.</p> <p>To call one of this class’s methods you have to use the <tt class="docutils literal"><span class="pre">get</span></tt> method in the following way: <tt class="docutils literal"><span class="pre">PluginManagerSingleton.get().themethodname(theargs)</span></tt></p> <p>To set up the various coonfigurables variables of the PluginManager’s behaviour please call explicitly the following methods:</p> <blockquote> <div><ul class="simple"> <li><tt class="docutils literal"><span class="pre">setCategoriesFilter</span></tt> for <tt class="docutils literal"><span class="pre">categories_filter</span></tt></li> <li><tt class="docutils literal"><span class="pre">setPluginPlaces</span></tt> for <tt class="docutils literal"><span class="pre">directories_list</span></tt></li> <li><tt class="docutils literal"><span class="pre">setPluginInfoExtension</span></tt> for <tt class="docutils literal"><span class="pre">plugin_info_ext</span></tt></li> </ul> </div></blockquote> <dl class="classmethod"> <dt id="yapsy.PluginManager.PluginManagerSingleton.get"> <em class="property">classmethod </em><tt class="descname">get</tt><big>(</big><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManagerSingleton.get" title="Permalink to this definition">¶</a></dt> <dd><p>Actually create an instance</p> </dd></dl> <dl class="classmethod"> <dt id="yapsy.PluginManager.PluginManagerSingleton.setBehaviour"> <em class="property">classmethod </em><tt class="descname">setBehaviour</tt><big>(</big><em>list_of_pmd</em><big>)</big><a class="headerlink" href="#yapsy.PluginManager.PluginManagerSingleton.setBehaviour" title="Permalink to this definition">¶</a></dt> <dd><p>Set the functionalities handled by the plugin manager by giving a list of <tt class="docutils literal"><span class="pre">PluginManager</span></tt> decorators.</p> <p>This function shouldn’t be called several time in a same process, but if it is only the first call will have an effect.</p> <p>It also has an effect only if called before the initialisation of the singleton.</p> <p>In cases where the function is indeed going to change anything the <tt class="docutils literal"><span class="pre">True</span></tt> value is return, in all other cases, the <tt class="docutils literal"><span class="pre">False</span></tt> value is returned.</p> </dd></dl> </dd></dl> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <p class="logo"><a href="index.html"> <img class="logo" src="_static/yapsy-big.png" alt="Logo"/> </a></p> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">PluginManager</a><ul> <li><a class="reference internal" href="#role">Role</a></li> <li><a class="reference internal" href="#plugin-description-policy">Plugin Description Policy</a><ul> <li><a class="reference internal" href="#plugin-info-file-format">Plugin Info File Format</a></li> </ul> </li> <li><a class="reference internal" href="#changing-the-default-behaviour">Changing the default behaviour</a></li> <li><a class="reference internal" href="#extensibility">Extensibility</a></li> <li><a class="reference internal" href="#api">API</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="IPlugin.html" title="previous chapter">IPlugin</a></p> <h4>Next topic</h4> <p class="topless"><a href="PluginInfo.html" title="next chapter">PluginInfo</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/PluginManager.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="PluginInfo.html" title="PluginInfo" >next</a> |</li> <li class="right" > <a href="IPlugin.html" title="IPlugin" >previous</a> |</li> <li><a href="index.html">Yapsy 1.10.2 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2010-2013, Thibauld Nion. Last updated on Oct 05, 2013. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. </div> </body> </html>