django-simple-plugins

A simple yet powerful and configurable tool for adding plugins to your Django project.


License
MIT
Install
pip install django-simple-plugins==0.1.2

Documentation

Django Simple Plugins

Django Simple Plugins is an app for Django that provides a simple yet flexible system to add a plugin layer to your project. Works with Django 1.7

Installation

Install Django plugins with pip:

pip install django-simple-plugins

Add 'plugins' to the list of installed apps in your settings.py file:

...
'plugins',
...

Add a PLUGINS_DIR setting to your settings.py with the directory where you are going to store your plugins. For instance:

...
PLUGINS_DIR = os.path.join(BASE_DIR, 'my_plugins')
...

Add the plugins urls to your urls.py file:

...
urlpatterns = patterns('',
    url(r'^admin/', include(admin.site.urls)),
    url(r'^plugins/', include('plugins.urls')),
)
...

Execute ./manage.py migrate

Writing your first plugins

As a very simple example, imagine that we want to delegate the "greet user" functionality to a plugin system. You want something a bit fancier than this:

def greet(request):
    greeting = 'Hello ' + request.user.username
    return HttpResponse(greeting)

For example, based on who the user is, you want a greeting like "Hello mighty Superman" or "Hello mighty, super Batman".

import plugins

def greet(request):
    adjectives = plugins.execute_plugins(type='GREETING', context={
        'username': request.user.username
    }, initial_input=[])
    greeting = 'Hello %s %s' % (', '.join(adjectives), request.user.username)
    return HttpResponse(greeting)

We want to define a series of plugins of type "GREETING" that return a list of adjective based on a context that provides the username.

Let's write the first plugin. In the directory defined by PLUGINS_DIR add the file greeter_plugin_1.py with this content:

plugin_type = 'GREETING'
verbose_name = 'Greeting plugin 1 - Mighty'

def run(options, context, input):
    if context['username'] in options['mighty_users']:
        input += 'mighty'

    return input

Each plugin must define a plugin_type and a run() function. They can define a verbose_name Each run function is pass the options passed by the configuration (see below), an optional context and an input. Since the plugins are executed in a chained fashion, the first plugin to be executed is passed the initial_input (in our case []) or None. The subsequent plugins are passed the return value of the previous plugins.

Let's write the others:

# greeter_plugin_2.py
plugin_type = 'GREETING'
verbose_name = 'Greeting plugin 2 - Super'

def run(options, context, input):
    if context['username'] in options['super_users']:
        input += 'super'

    return input
# greeter_plugin_3.py
plugin_type = 'GREETING'

def run(options, context, input):
    if context['username'] in options['stinky_users']:
        input += 'stinky'

    return input
# goodbye_plugin_1.py
plugin_type = 'GOODBYE'

def run(options, context, input):
    pass

Visiting the admin page, we have a list of our plugins conveniently grouped by plugin type.

Screenshot 1

Three things to notice. We don't want to insult our users, so we can disable the third plugin and it will be skipped. If you don't provide a verbose_name, the file name will be used (see greeter_plugin_3). Finally, the plugins are sortable. You can drag them to arrange the order of execution. For example, If you'd like to have "super, mighly Batman" instead of "mighty, super batman", just drag the Super plugin before the other:

Screenshot 2

We only have one last thing to do. As you might have noticed, we read some parameter from the options dictionary. In the admin interface you can specify a JSON string that will be passed as a dictionary to the plugin. For instance:

Screenshot 2