Introduction

When considering to write a plugin for Deluge, one must first understand the basic design of Deluge. Deluge is split in two, the core and the user-interface of which there could be many. When writing your plugin you will be writing a Core portion and, perhaps, many different UI portions. This may sound complicated and at times it can be, but once you get the hang of it, it becomes second-hand.

Skill Checklist

This is a list of recommended skills or knowledge that you may need to successfully write a plugin. This is by no means required, but can serve as a starting point if you're not sure what you need to know. It may also be a good idea to read ​How To Write a Client first, to give you some idea of how a UI would interact with the Core.

• Python
• Twisted, specifically Deferreds
• GTK and possibly Glade
• Javascript for the WebUI portions

Designing Your Plugin

Deluge has the ability to function in a headless environment with only the daemon (Core) portion running. Various user-interfaces will connect from time to time and view or modify the session, but may not be connected all the time, so the "smarts" of your plugin should reside in the core. You should also be aware that multiple UIs may be connected at the same time and they will need to behave correctly in terms of your plugin. Typically, the best place to start writing your plugin is in the Core portion since it will contain most of the plugin logic, with the UI portions typically responsible for displaying and modifying plugin configuration or providing the user with status updates.

Conceptually you'll want to view your plugin as a collection of separate programs with your UI programs interfacing with your Core program through an RPC interface. They do not share the same space in memory and may in fact be run on different computers, so information from the Core will need to be accessible to the clients through it's RPC exported functions -- and you can't send any object over this interface, only the basic types.

Getting Started

The easiest way to get started is to use the ​create_plugin.py script in the appropriate branch in our SvnRepo?. Alternatively, you can use other plugins as a template if you prefer.

Running the script:

$ python create_plugin.py --name MyPlugin --basepath . --author-name "Your Name" --author-email "yourname@example.com"

This should create a directory called myplugin under which should be a collection of directories and files which will form the base of your plugin.

The file structure should look like this (perhaps a bit more since it does a build right away):

myplugin/
|-- create_dev_link.sh
|-- myplugin
|   |-- __init__.py
|   |-- common.py
|   |-- core.py
|   |-- data
|   |   `-- config.glade
|   |-- gtkui.py
|   |-- template
|   |   `-- default.html
|   `-- webui.py
`-- setup.py

Modifying Metadata

You may want to change or add some stuff to your plugin's metadata, such as the description or perhaps a URL for your project. To do this, navigate to your myplugin directory and open up the setup.py file. You will see a few different properties and modifying them should be self-explanatory, but you should refrain from changing the plugin name.

Building The Plugin

Whenever you want to test out your plugin in Deluge, you will need to build it into an egg.

First off, navigate to your myplugin base directory, you should see a setup.py file in there. Next, run the following command:

$ python setup.py bdist_egg

It's as simple as that. You can also use this method to create an egg for distribution to other Deluge users. The egg will be located in the dist directory.

Core Plugin

Introduction

We'll start off by writing the Core portion of our plugin. In this example, we'll do some pretty trivial things to demonstrate some of the ideas and components associated with the plugin development process. We'll look at configuration, exporting rpc functions, interacting with Core components and timers.

Hello Wo...UI!

Let's start with a look at what our create_plugin.py script created for us in the core.py file.

from deluge.log import LOG as log
from deluge.plugins.pluginbase import CorePluginBase
import deluge.component as component
import deluge.configmanager
from deluge.core.rpcserver import export

DEFAULT_PREFS = {
    "test":"NiNiNi"
}

class Core(CorePluginBase):
    def enable(self):
        self.config = deluge.configmanager.ConfigManager("myplugin.conf", DEFAULT_PREFS)

    def disable(self):
        pass

    def update(self):
        pass

    @export
    def set_config(self, config):
        "sets the config dictionary"
        for key in config.keys():
            self.config[key] = config[key]
        self.config.save()

    @export
    def get_config(self):
        "returns the config dictionary"
        return self.config.config

We won't worry about the imports at the top, you should be able to surmise what these are for and if not, you'll see them in use later in this example. What we will worry about, and what seems to be right in our face, is plugin configuration.

self.config = deluge.configmanager.ConfigManager("myplugin.conf", DEFAULT_PREFS)

We see here that we're using Deluge's ConfigManager? to handle loading our config with some default preferences. All you really need to know is that this config object will act much like a dictionary object, but has some special methods like save() for writing the config to disk. You don't need to necessarily call save() yourself, as the config object will handle this on it's own when the config values change.

You can read here: ​http://deluge-torrent.org/docs/current/modules/config.html for more information on the Config class.

Before we go too much further, you'll notice that this config file loading is done within the enable method of our Core plugin class. Whenever a plugin is enabled by the user or on start-up, this method will be called. Likewise for the disable method which is called whenever the plugin is disabled. Simple, right?

    @export
    def set_config(self, config):
        "sets the config dictionary"
        for key in config.keys():
            self.config[key] = config[key]
        self.config.save()

    @export
    def get_config(self):
        "returns the config dictionary"
        return self.config.config

Whoa, what's this? It's our first two rpc exported methods of course!