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
240 __docformat__ = "restructuredtext en"
241