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.
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.
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:
which will load the file 'myres.rsrc' in the same directory as the referring file.from twisted.python.util import sibPath myResourceData = open(sibPath(__file__,"myres.rsrc")).read()
Plugins are distributed as archives using the .zip, .tar.gz, or .tar.bz2 file format.