Yapsy is used enough for your favorite search provider to have good chances of finding some examples of yapsy being used in the wild.
However if you wonder how a specific functionality can be used, you can also look at the corresponding unit test (in the test folder packaged with yapsy’s sources).
Yapsy uses Python’s standard logging module to record most important events and especially plugin loading failures.
When developping an application based on yapsy, you’ll benefit from looking at the ‘debug’ level logs, which can easily be done from your application code with the following snippet:
import logging
logging.basicConfig(level=logging.DEBUG)
Also, please note that yapsy uses a named logger for all its logs, so that you can selectively activage debug logs for yapsy with the following snippet:
import logging
logging.getLogger('yapsy').setLevel(logging.DEBUG)
If your application defines various categories of plugins with the yapsy’s built-in mechanism for that, please keep in mind the following facts:
- a plugin instance is attributed to a given category by looking if it is an instance, even via a subclass, of the class associated to this category;
- a plugin may be attributed to several categories.
Considering this, and if you consider using several categories, you should consider the following tips:
- don’t associate any category to ``IPlugin`` (unless you want all plugins to be attributed to the corresponding category)
- design a specific subclass of IPlugin for each category
- if you want to regroup plugins of some categories into a common category: do this by attributing a subclass of IPlugin to the common category and attribute to the other categories specific subclasses to this intermediate mother class so that the plugin class inheritance hierarchy reflects the hierarchy between categories (and if you want something more complex that a hierarchy, you can consider using mixins).
There must be only one plugin defined per module. This means that you can’t have two plugin description files pointing at the same module for instance.
Because of the “categorization by inheritance” system, you musn’t directly import the subclass of IPlugin in the main plugin file, instead import its containing module and make your plugin class inherit from ContainingModule.SpecificPluginClass as in the following example.
The following code won’t work (the class MyBasePluginClass will be detected as the plugin’s implementation instead of MyPlugin):
from myapp.plugintypes import MyBasePluginClass
class MyPlugin(MyBasePluginClass):
pass
Instead you should do the following:
import myapp.plugintypes as plugintypes
class MyPlugin(plugintypes.MyBasePluginClass):
pass
When packaging plugins in a distutils installer or as parts of an application (like for instance with py2exe), you may want to take care about the following points:
See also a more detailed example for py2exe on Simon on Tech’s Using python plugin scripts with py2exe.
If you intend to modify yapsy’s sources and to contribute patches back, please respect the following conventions: