['Development/Plugins']

= Plugins Demo1 = 


''I'm writing these docs while trying to create my first plugin.
And it's easiest to write docs the when you've never done something before.
these docs will not follow best practices because of lack of experience''

= Purpose =

Creating a basic plugin.

This plugin adds a status-field and a setter to the core.

It does not save the state,and all information is lost after a restart of the daemon.

Test code:
{{{
from deluge.ui.client import sclient
sclient.set_core_uri()
id = sclient.get_session_state()[0] #1st torrent

print "before:",id, sclient.get_torrent_status(id, ['name','label'])

sclient.label_set_label(id,'')
print "after reset:",sclient.get_torrent_status(id, ['name','label'])

sclient.label_set_label(id,'movie')
print "after set:",sclient.get_torrent_status(id, ['name','label'])
}}}

Result:
{{{
before: f2b609578473f6a29d3123ba0897213b3c1bbcda {'name': 'aesmsclient_0.2.1.jar', 'label': ''}
after reset: {'name': 'aesmsclient_0.2.1.jar', 'label': ''}
after set: {'name': 'aesmsclient_0.2.1.jar', 'label': 'movie'}
}}}

= Plugin Core Code = 
core.py:
{{{
#
# a simple plugin with memory-loss
# adds a status-field,does not remember settings after restart of daemon.

from deluge.log import LOG as log
from deluge.plugins.corepluginbase import CorePluginBase

class Core(CorePluginBase):    
    def enable(self):
        log.debug("*** START , HI!!!***")
        self.labels = {}
        # Register the 'label' status field
        self.plugin.register_status_field("label", self._get_label)        
        log.debug("Label plugin enabled..")
    
    def disable(self):
        # De-register the label field
        self.plugin.deregister_status_field("label")

    def update(self):
        pass
            
    ## Status field function ##
    def _get_label(self, torrent_id):
        #return label or empty string.
        return self.labels.get(torrent_id, '')
        
    ## Setter ##
    def export_set_label(self, torrent_id, label):
        log.debug("set label %s=%s" % (torrent_id, label))
        self.labels[torrent_id] = str(label)
}}}

= Notes =

 * all methods starting with export_ are available in s/aclient prefixed by the plugin-name (export_set_label-->sclient.label_set_label). 
 * self.plugin.register_status_field/self.plugin.register_status_field add fields to s/aclient.get_torrent_status.
 * the enable, disable and update methods are called by the core.


= eggs =

The good and bad news about deluge 0.6 plugins is that it uses eggs. 
Deployment of eggs is easy, but they do need some meta-data.

We're not addressing deployment now, python-eggs allow directory based development too. And IMHO it's easier to develop with directory's than with zipped eggs.


''an example is linked at the bottom of this page.

Minimal structure of a deluge plugin directory:

'''Place name.egg in ~/.config/deluge/plugins''
{{{
name.egg/
name.egg/EGG-INFO
name.egg/EGG-INFO/PKG_INFO
name.egg/EGG-INFO/entry_points.txt
name.egg/name/
name.egg/name/__init__.py
name.egg/name/core.py
}}}

= Meta data =
PKG_INFO:
{{{
Metadata-Version: 1.0
Name: label
Version: 0.1
Summary: Deluge Label Plugin
Home-page: http://deluge-torrent.org
Author: Your Name
Author-email: your@email.com
License: GPLv2
Description: UNKNOWN
Platform: UNKNOWN
}}}
entry_points.txt:
{{{
[deluge.plugin.core]
Label = label:CorePlugin
}}}
_ _init_ _.py:
{{{
from deluge.log import LOG as log

from deluge.plugins.init import PluginBase

class CorePlugin(PluginBase):
    def __init__(self, plugin_api, plugin_name):
        # Load the Core portion of the plugin
        try:
            from core import Core
            self.plugin = Core(plugin_api, plugin_name)
        except Exception, e:
            log.debug("Did not load a Core plugin: %s", e)
}}}