Twisted Plugins

Rationale

In order to simplify distribution of servers which use Twisted, and to allow them to be used with each other, there is a convention for distributing a set of functionality. This convention may grow over time (most likely to include more metadata), as it is currently extremely simple.

Definition

A plugin is simply a directory. A plugin must be a valid Python package, that is, it must contain an __init__.py. A plugin may contain subpackages, or non-package resource directories.

A plugin should also contain a file named config.tac. This file is a Twisted Application Configuration. It must be a valid Python file. It must bind a variable called 'application' to an instance of a twisted.internet.main.Application. This is for use with the -g option to twistd.

From the user's perspective, a plugin named MyPlugin with a config.tac may be dropped in their ~/TwistedPlugins or Twisted-x.x.x/plugins directory, and then run with twistd -g MyPlugin. From a developer's perspective, code from that plugin may simply be used by calling import MyPlugin. Plugins that do not include a config.tac for some reason should be referred to as "code-only" plugins or "non-runnable" plugins.

Conventions

The function twisted.python.util.sibPath can be used in config.tac or anywhere else a plugin needs to load a resource file. Canonical usage is something like this:

from twisted.python.util import sibPath
myResourceData = open(sibPath(__file__,"myres.rsrc")).read()
      
which will load the file 'myres.rsrc' in the same directory as the referring file.

Plugins are distributed as archives using the .zip, .tar.gz, or .tar.bz2 file format.