Plugin API

This document describes the methods and properties of the plugin API provides by the sushi module. The module provides a basic class called Plugin, which can be inherited. The methods it provides are described below.

Further the sushi module provides constants to describe the user configuration interface for the plugin. There are two variables every plugin module should define:

1. plugin_info
2. plugin_options

What about providing a parse_from in Plugin or sushi?

The first represents generic informations about the plugin in form of a tuple:

plugin_info = ("Generic description is placed here.", "1.2.0 beta", "Marian Tietz")

The second, plugin_options, describes the interface of the user configuration dialog for the plugin. This value is also a tuple with *n* sub-tuples each counting 5 elements.

plugin_options = (
	("c_test", "Test string", sushi.TYPE_STRING, "Default test"),
	("c_num", "Test number", sushi.TYPE_NUMBER, 42)
)

The first field of such a sub-tuple represents the configuration value to be set. The second field is the label the input line could be identified with. The third determines which kind of input we have. There are the following types available:

TYPE_PASSWORD is for inputs without recognizing the written text (hidden chars) and TYPE_CHOICE is for multiple choice answers. TYPE_CHOICE is the most complex type to define:

plugin_options = (
	("my_choice", "Make your choice", sushi.TYPE_CHOICE, (
		("Choice #1","1"),
		("Choice #2","2"),
		("Choice #3","3")))
)

The standard item is the first. If you select one, my_choice is set to the value in the second field. For example, if you choose “Choice #1”, my_choice will be “1”.

• Arguments: None

Called when the plugin is loaded.

def __init__ (self):
  sushi.Plugin.__init__(self, "foo")

• Arguments: maki_interface

Called if the connection to maki is etablished. (Event)

• Arguments: maki_interface

Called if the connection to maki is aborted. (Event)

• Arguments: None

Called when the plugin is unloaded.

def unload (self):
  sushi.Plugin.unload(self)

• Arguments: None

Returns a DBus interface connected to de.ikkoku.sushi or None.

self.bus = self.get_bus()
self.bus.shutdown("")

• Arguments: server (string)

Returns the nick on server or None.

if nick == self.get_nick("Freenode"):
  # "Freenode" is the server name defined in maki so this can be everything
  pass

• Arguments: name (string), handler (function)
• Returns: True on successful connection, False otherwise

This function connects the given handler function to the signal identified by the name given. The sushi application providing this API function handles a maki reconnect and reconnects the signal if needed. Also signals are automatically disconnected on plugin unload.

• Arguments: name (string), handler (function)
• Returns: True on successful disconnection, False otherwise.

• Arguments: command (string), callback (function)
• Returns: True on successful add, False otherwise.

Connects the given command to callback. The callback will be called with the three arguments server, channel and args. server and channel are strings, while args is a string array containing the command parameters (without the command itself). Returns True (on success) or False.

Registered commands will be unregistered automatically on plugin unload.

def foo_cb (server, channel, args):
  print server, channel
  for arg in args:
    print arg
 
self.add_command("foo", self.foo_cb)

• Arguments: command (string), callback (function)
• Returns: True on successful disconnection, False otherwise.

Disconnects the given command from callback.

def unload (self):
  self.remove_command("foo", self.foo_cb)

• Arguments: key (string), value (string)

Sets the option key to the given value. Allows plugins to save configuration values to a file.

self.set_config("foo_enabled", str(True))

• Arguments: key (string)
• Returns: string or None

Returns the value of config value for key from the configuration file or None.

self.get_config("foo_enabled")

• Arguments: message (string)

Displays an error message.

self.display_error("foo failed to obtain bar.")

# file foo.py
import sushi
 
plugin_info = (
  "Does foo.",
  "1.0",
  "Anony Mouse"
)
 
class foo (sushi.Plugin):
 
  def __init__ (self):
    sushi.Plugin.__init__(self, "foo")
 
    self.do_foo = bool(self.get_config("do_foo"))
 
    self.add_command("foo", self.foo_cb)
    self.connect_signal("message", self.message_cb)
 
  def unload (self):
    self.disconnect_signal("message", self.message_cb)
    self.remove_command("foo", self.foo_cb)
 
  def foo_cb (self, server, target, args):
    self.set_config("do_foo", str(not self.do_foo))
 
  def message_cb (self, time, server, from_str, channel, text):
    nick = from_str.split("!")[0]
 
    if nick == self.get_nick(server):
      self.display_error("foo")
    else:
      self.display_error("bar")