[Twisted-Python] twisted.plugin (revised) documentation?

[Jp Calderone]

On Thu, 23 Jun 2005 14:43:38 -0400, Pedro Sanchez <psanchez at nortel.com> wrote:
>Hello,
>
>Where can I find documentation on the current twisted.plugin framework?
>
>The document "Writing a New Plug-In for mktap" at
>http://twistedmatrix.com/projects/core/documentation/howto/plugin.html
>seems to have outdated information. When I run the mktap command, as
>instructed there, this is what I get:
>
>$ mktap qotd
>TwistedQuotes/plugins.tml:7: DeprecationWarning: The
>twisted.python.plugin system is deprecated.  See twisted.plugin for the
>revised edition.  tapname="qotd")
>
>I'm running twisted 2.0.1 and I can't find any new documentation. The
>document above is also found in doc/core/howto/plugin.html of the
>current twisted distribution.
>

It's on my list of things to write.

In brief, the way plugins are implemented now is:

1) in a module in the twisted.plugins (plural) package.  Such modules should be named in such a way so as not to conflict with plugins provided by other parties (eg, Twisted uses the convention of "twisted_foo" for plugins it itself offers).  Installers should place plugin modules in the twisted/plugins/ directory and call list(twisted.plugin.getPlugin(twisted.plugin.IPlugin)) afterwards to regenerate the system cache (not doing so is only detrimental in that operation without the cache is much slower).  Uninstallers should do something similar to avoid leaving stale cache entries (these will be found and pruned, but lead to at least one ugly traceback, and for a system-wide install, the user probably will not have access to rewrite the cache with bogus entries removed).  As a convenience to developers, plugins placed in a _directory_ (not a package) named "twisted/plugins/" in any directory in sys.path will automatically be found by the plugin system as well.  This avoids the install process during development and for testing.

2) In these modules, names bound to objects which provide (z.i terminology) twisted.plugin.IPlugin will be considered plugin objects and can potentially be returned by twisted.plugin.getPlugins()

3) Objects providing IPlugin should also provide some other application-specific interface.  When calling twisted.plugin.getPlugins(IFoo), only objects providing IFoo will be returned.

4) Plugin "client" code (that is, code calling getPlugin) is then responsible for calling methods appropriate to the interface it passed.

For examples of this, see the twisted_ modules in twisted/plugins/.

Hope this helps,

Jp