Welcome to extender’s documentation!¶
extender is a simple plug-in/extension system on Python
User’s guide¶
Installation¶
If you are familiar with Python, it is strongly suggested that you install everything in virtualenv.
If you are using OS X , make sure you have installed the Command Line Tools .
Install using pip¶
Install extender via pip is easy
(sudo) pip install extender
and you can also install from the latest source code with pip
(sudo) pip install https://github.com/messense/extender/archive/master.zip
Install with Git¶
Install with git can always have the latest code
git clone git://github.com/messense/extender.git
cd extender
python setup.py install
Write your plugin¶
Plugin layout¶
A plugins layout generally looks like the following
setup.py
pluginname/
pluginname/__init__.py
pluginname/plugin.py
The __init__.py file should contain no plugin logic, and at most, a __version__ = ‘x.x.x’ line. For example, if you want to pull the version using pkg_resources (which is what we recommend), your file might contain
try:
__version__ = __import__('pkg_resources') \
.get_distribution(__name__).version
except Exception:
__version__ = 'unknown'
Plugin class¶
Inside of plugin.py, you’ll declare your Plugin class
# -*- coding: utf-8 -*-
from extender import Plugin
import plugin1
class PluginName(Plugin):
title = 'Plugin Name'
slug = 'pluginname'
description = 'My awesome plugin!'
version = plugin1.__version__
author = 'Your Name'
author_url = 'https://github.com/yourname/pluginname'
def test_func(self, msg):
return msg
You should provider at least title, version attributes in your plugin class and define whatever method as you wish.
Register your plugin¶
You can register your plugin via entry_points in your setup.py
#!/usr/bin/env python
# -*- coding: utf-8 -*-
from setuptools import setup
setup(
name='pluginname',
version='0.0.1',
author='Your name',
author_email='Your Email address',
url='https://github.com/yourname/pluginname',
packages=[
'pluginname'
],
description='plugin description',
install_requires=[
'extender',
],
include_package_data=True,
entry_points={
'extender.plugins': [
'pluginname = pluginname.plugin:PluginName',
]
},
)
You can change entry_points key extender.plugins to whatever you want.
That’s it! Users will be able to install your plugin via python setup.py install. And your plugin will be registered to that entry_points automatically, then you can install/load all these awesome plugins in your code.
Install and manage plugins¶
Setup a plugin manager¶
To install your awesome plugins, you should initialize a PluginManager first
from extender import PluginManager
plugins = PluginManager()
Install plugins¶
With a instance of PluginManager class, we can install plugins of a specific entry_points by calling the install method of PluginManager
from extender import PluginManager
plugins = PluginManager()
plugins.install('extender.plugins')
To setup a plugin manager and install plugins quickly you can do it by
from extender import PluginManager
plugins = PluginManager(entry_points='extender.plugins')
Use plugins¶
You can use plugins.call(func_name, *args, **kwargs) method to invoke the method func_name on every plugin and return a list of results which contains return value of each invoked method of plugins
from extender import PluginManager
plugins = PluginManager()
plugins.install('extender.plugins')
result_list = plugins.call('say', 1, msg='hello')
To get single value of the first invoked plugin’s return value, use first instead of call
from extender import PluginManager
plugins = PluginManager()
plugins.install('extender.plugins')
result = plugins.first('say', 1, msg='hello')
If you want to apply some method of plugins on a variable and return the value(maybe modified by plugins), you can use apply
from extender import PluginManager
plugins = PluginManager()
plugins.install('extender.plugins')
value = "Hello world!"
value = plugins.apply('greet', value)