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:

• "plugin_info"
• "plugin_options"

Type	Name
Method	#__init__
Method	unload
Method	get_bus
Method	get_nick
Method	connect_signal
Method	disconnect_signal
Method	add_command
Method	remove_command
Method	set_config
Method	get_config
Method	display_error
Method	parse_from
Event	maki_connected
Event	maki_disconnected

plugin_info¶

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

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

plugin_options¶

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.

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

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
TYPE_STRING
TYPE_PASSWORD
TYPE_NUMBER
TYPE_BOOL
TYPE_CHOICE
TYPE_LIST
TYPE_MAP

"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:

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

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".

TYPE_LIST defines itself as follows:

1("my_list", "Select some", sushi.TYPE_LIST, ("Cake","Cream","Cat"))

TYPE_MAP is pretty much like maps in python:

1("my_map", "Select some", sushi.TYPE_MAP,
2    (("Cake","Delicious"),("Cream","Tasty"),("Cat","Hairy")))

Example:

1("my_map", "Select some", sushi.TYPE_MAP,
2    (("Cake","Delicious"),("Cream","Tasty"),("Cat","Hairy")))

Lists and Maps are saved in the JSON format, so one can easily unpack them
from the config via

1import json
2map = json.loads(self.get_config("my_map"))
3print map["Cake"] # -> Delicious

init¶

• Arguments: None
  Called when the plugin is loaded.

Example¶

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

maki_connected¶

• Arguments: maki_interface
  Called if the connection to maki is etablished. (Event)

maki_disconnected¶

• Arguments: maki_interface
  Called if the connection to maki is aborted. (Event)

unload¶

• Arguments: None
  Called when the plugin is unloaded.

Example¶

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

get_bus¶

• Arguments: None
  Returns a DBus interface connected to "de.ikkoku.sushi" or "None".

Example¶

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

get_nick¶

• Arguments: server (string)
  Returns the nick on "server" or "None".
  h3. Example

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

connect_signal¶

• 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.

disconnect_signal(name, handler)¶

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

add_command (command, callback)¶

• 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.

Example¶

1def foo_cb (server, channel, args):
2  print server, channel
3  for arg in args:
4    print arg
5
6self.add_command("foo", self.foo_cb)

remove_command (command, callback)¶

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

Disconnects the given "command" from "callback".

Example¶

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

set_config¶

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

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

Example¶

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

get_config¶

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

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

Example¶

1self.get_config("foo_enabled")

display_error¶

• Arguments: message (string)
  Displays an error "message".

parse_from¶

• Arguments: host_string (string)
  Splits up the host string in nick, ident and hostmask.
  Should the host_string only be a nick (missing "!") or does only contain "nick!ident",
  the nick is returned as .

Example¶

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

Example Plugin¶

 1# file foo.py
 2import sushi
 3
 4plugin_info = (
 5  "Does foo.",
 6  "1.0",
 7  "Anony Mouse" 
 8)
 9
10class foo (sushi.Plugin):
11
12  def __init__ (self):
13    sushi.Plugin.__init__(self, "foo")
14
15    self.do_foo = bool(self.get_config("do_foo"))
16
17    self.add_command("foo", self.foo_cb)
18    self.connect_signal("message", self.message_cb)
19
20  def unload (self):
21    self.disconnect_signal("message", self.message_cb)
22    self.remove_command("foo", self.foo_cb)
23
24  def foo_cb (self, server, target, args):
25    self.set_config("do_foo", str(not self.do_foo))
26
27  def message_cb (self, time, server, from_str, channel, text):
28    nick = from_str.split("!")[0]
29
30    if nick == self.get_nick(server):
31      self.display_error("foo")
32    else:
33      self.display_error("bar")