Package yapsy
[hide private]

Source Code for Package yapsy

  1  """ 
  2  ================================ 
  3  Yapsy: Yet Another Plugin SYstem 
  4  ================================ 
  5   
  6  A simple plugin system for Python applications 
  7  ============================================== 
  8   
  9  .. image::  artwork/yapsy-big.png 
 10   
 11  .. |Yapsy| replace:: **Yapsy** 
 12  .. |Yapsy-icon| image:: artwork/yapsy.png  
 13  .. |SourceForge.net| image:: http://sflogo.sourceforge.net/sflogo.php?group_id=208383&type=5 
 14                       :alt: SourceForge.net 
 15  .. |CC-BYSA| image:: http://i.creativecommons.org/l/by-sa/3.0/88x31.png 
 16               :alt: Creative Commons License 
 17   
 18  Overview 
 19  -------- 
 20   
 21  Yapsy's main purpose is to offer a way to easily design a plugin 
 22  system in Python, and motivated by the fact that many other Python 
 23  plugin system are either too complicated for a basic use or depend on 
 24  a lot of libraries. Yapsy only depends on Python's standard library. 
 25   
 26  |yapsy| basically defines two core classes: 
 27   
 28  - a fully functional though very simple ``PluginManager`` class 
 29   
 30  - an interface ``IPlugin`` for classes implementing plugins for this PluginManager. 
 31   
 32  The ``PluginManager`` 
 33  ~~~~~~~~~~~~~~~~~~~~~ 
 34   
 35  The ``PluginManager`` will load plugins that enforce the `Plugin 
 36  Description Policy`_, and offers the most simple methods to activate 
 37  and deactivate the loaded plugins. 
 38   
 39  It may also classify the plugins in various categories, but this 
 40  behaviour is optional and if not specified elseway all plugins are 
 41  stored in the same default category. 
 42   
 43  The provided classes have been designed in order to be as easy as 
 44  possible to extend_. 
 45   
 46   
 47  The ``IPlugin`` base class 
 48  ~~~~~~~~~~~~~~~~~~~~~~~~~~ 
 49   
 50  When using |yapsy| in your own software, you'll probably want to build 
 51  derived classes of the ``IPlugin`` class as it is a mere interface 
 52  with no specific functionality.  
 53   
 54  Your software's plugins should then inherit your very own plugin class 
 55  (itself derived from ``IPlugin``). 
 56   
 57  Where and how to code these plugins is explained in the section about 
 58  `Plugin Description Policy`_ . 
 59   
 60   
 61  Plugin Description Policy 
 62  ------------------------- 
 63   
 64  When creating a ``PluginManager`` instance, one should provide it with 
 65  a list of directories where plugins may be found. In each directory, 
 66  a plugin should contain the following elements: 
 67   
 68  *Standard* plugin 
 69  ~~~~~~~~~~~~~~~~~ 
 70   
 71    ``myplugin.yapsy-plugin``  
 72    
 73        A *plugin info file* identical to the one previously described. 
 74    
 75    ``myplugin`` 
 76    
 77        A directory ontaining an actual Python plugin (ie with a 
 78        ``__init__.py`` file that makes it importable). The upper 
 79        namespace of the plugin should present a class inheriting the 
 80        ``IPlugin`` interface (the same remarks apply here as in the 
 81        previous case). 
 82   
 83   
 84  *One file* plugin 
 85  ~~~~~~~~~~~~~~~~~ 
 86   
 87    ``myplugin.yapsy-plugin``  
 88          
 89      A *plugin info file* which is identified thanks to its extension, 
 90      see the `Plugin Info File Format`_ to see what should be in this 
 91      file. 
 92       
 93     
 94      The extension is customisable at the ``PluginManager``'s 
 95      instanciation, since one may usually prefer the extension to bear 
 96      the application name rather than |yapsy|'s. 
 97     
 98    ``myplugin.py`` 
 99     
100       The source of the plugin. This file should at least define a class 
101       inheriting the ``IPlugin`` interface. This class will be 
102       instanciated at plugin loading and it will be notified the 
103       activation/deactivation events. 
104      
105   
106   
107  Plugin Info File Format 
108  ----------------------- 
109   
110   
111  The plugin info file gathers, as its name suggests, some basic 
112  information about the plugin. On one hand it gives crucial information 
113  needed to be able to load the plugin. On the other hand it provided 
114  some documentation like information like the plugin author's name and 
115  a short description fo the plugin functionality. 
116   
117   
118  Here is an example of what such a file should contain:: 
119   
120   [Core] 
121   Name = Simple Plugin 
122   Module = SimplePlugin 
123   
124   [Documentation] 
125   Author = Thibauld 
126   Version = 0.1 
127   Website = http://yapsy.sourceforge.net  
128   Description = A simple plugin usefull for basic testing 
129   
130  .. _extend: 
131   
132  Extensibility 
133  ------------- 
134   
135  The classes defined by |yapsy| have been build with the minimum number 
136  of functionalities needed for them to achieve their purpose. This has 
137  been done in order to make it as easy as possible to extend this class 
138  and adapt them to any specific need. 
139   
140  However, some basic extension have been implemented. Each extension 
141  (by inheritance) of the ``PluginManager`` intends to add only one 
142  functionality as in the following instance: 
143   
144  ``PluginManagerSingleton`` 
145   
146    Adds the behaviour of a singleton to the ``PluginManager`` class. 
147   
148   
149  ``ConfigurablePluginManager``  
150   
151    Implements a ``PluginManager`` that is able to use a configuration 
152    file through an interface compatible with the standard ConfigParser_ 
153    module. 
154   
155  .. _ConfigParser: http://docs.python.org/lib/module-ConfigParser.html 
156   
157   
158  ``VersionedPluginManager``  
159   
160    Able to manage several versions of a same plugin.  
161   
162   
163  ``AutoInstallPluginManager``  
164   
165    Automatically copy the plugin files to the right plugin directory.  
166   
167  .. _PluginManagerDecorator: ./yapsy.PluginManager.PluginManagerDecorator-class.html 
168   
169  See PluginManagerDecorator_ 's subclasses for more. 
170   
171   
172  Development 
173  ----------- 
174   
175   
176  |yapsy| 's development has been motivated by the MathBench_ project 
177  but it is now used in other (more advanced) projects like peppy_. 
178   
179  .. _MathBench: http://mathbench.sourceforge.net 
180  .. _peppy: http://www.flipturn.org/peppy/ 
181   
182  Its development is hosted `on Sourceforge`_. 
183   
184  .. _`on Sourceforge`: http://sourceforge.net/projects/yapsy/ 
185   
186  .. _BSD: http://www.opensource.org/licenses/bsd-license.php 
187   
188  The work is placed under the simplified BSD_ license in order to make 
189  it as easy as possible to be reused in other projects. Please note 
190  that the icon is not under the same license but under the Creative 
191  Common Attribution-ShareAlike license. 
192   
193  Any suggestion and help are much welcome ! 
194   
195   
196  References 
197  ---------- 
198   
199   
200  Other Python plugin systems already existed before |yapsy|. |yapsy|'s 
201  creation is by no mean a sign that these others plugin systems sucks 
202  :) It is just the results of me being slighlty lazy and as I had 
203  already a good idea of how a simple plugin system should look like, I 
204  wanted to implement my own [#older_systems]_. 
205   
206   
207  - setuptools_ seems to be designed to allow applications to have a 
208    plugin system. 
209   
210  .. _setuptools: http://cheeseshop.python.org/pypi/setuptools  
211   
212   
213  - Sprinkles_ seems to be also quite lightweight and simple but just 
214    maybe too far away from the design I had in mind. 
215   
216  .. _Sprinkles: http://termie.pbwiki.com/SprinklesPy  
217   
218   
219  - PlugBoard_ is certainly quite good also but too complex for me. It also 
220    depends on zope which considered what I want to do here is way too 
221    much. 
222   
223  .. _PlugBoard: http://developer.berlios.de/projects/plugboard/  
224   
225  .. [#older_systems] All the more because it seems that my modest 
226     design ideas slightly differ from what has been done in other 
227     libraries. 
228   
229  ---------- 
230   
231  Project hosted by SourceForge_ 
232   
233  |SourceForge.net|  
234   
235  .. _SourceForge: http://sourceforge.net 
236   
237  """ 
238   
239  # tell epydoc that the documentation is in the reStructuredText format 
240  __docformat__ = "restructuredtext en" 
241