how to write a plugin for the python reference-implementation of co2:


what is a plugin?

since co2 does not provide or produce any kind of content (whatever that
is...) it relies on plugins to fill a co2 network with data.

a plugin receives incoming messages as received by the server, and can
send out messages through the server.
the server simply passes on received messages to all it's plugins and
provides them with a send-method to send to the co2-network (ie. to all
plugins on all registered satellites)
additionally, a plugin can use the server's logging and debugging facilities.


overview:

plugins are organized as packages. on start-up, the server's loader scans
the plugin directory for packages that meet some prerequisits, loads and
initializes them.
a package can contain any number of modules, only those of which are loaded
that are listed in the __all__ variable of the package's  __init__.py (a
little like 'from ppp import *').
the loaded modules are searched for classes whose names begin with 'X_'
and that are subclasses of plugin.Co2Plugin. these classes are then
initialized and subsequently 'online', i.e. can send, receive, log and
debug through the server.


details:

basically all there is to do is to subclass Co2Plugin (in the file plugin.py
in plugins/examples) properly, all the rest is handled by the server.

Co2Plugin comes with all the necessary members:
 send(data_dict):
   sends data to the relay. in fact, this is the satellite's relay method
   (registry.Co2Registry._relay)
   data_dict: data to send as a dictionary {key1:value1, key2:value2,...}

 debug(caller, msg):
   puts out a message to the servers debug log
   caller: should be 'self', so the classname of the calling object (here the
     plugin) appears on the beginning of the line.
   msg: the message to log (type: string or object with __repr__ method)

 log(caller, msg):
   for now, does the same as debug

 name:
   a string in the form of package.module (for info and debugging, appears in
   the log)

 all of the above should NOT be overridden!

 receive(data_dict):
   called by the registry when a relayed message comes in, ie. the relay
   simply passes on the data (dictionary) it receives.
   this method MUST be overridden in order for your plugin to be usefull.
   this is where the work gets done.fill in the code you want executed on
   incomming messages.
   don't bother to return a value since it will be ignored.

 __exit__():
   called by the satellite on exit. if the plugin has to clean up before
   exiting (close files, stop threads...), override it.

for an example see plugins/example/example.py
for a mor advanced example see plugins/pd/ (pd patches to use with that are
in pd-patches)
