Plugin docs should state how to make plugin logic testable

	str4d reported
Trac ID	trac#6816
Type	defect
Created	2013-11-07 00:05:14Z

The documentation for the Twisted plugin system is not clear on how external code should be structured for testable plugin logic. The method used in the Twisted codebase is to put the plugin logic in the same module as the rest of their code, and to import the classes that implement IPlugin into a trivial .py file in twisted/plugins/. The documentation should reflect this.

Abbreviated IRC conversation showing my misunderstanding:

<str4d> How should I test a Twisted plugin? The spec requires that
the twisted/ folder does not contain an __init__.py but that kills
trial. Do I need to use getPlugins() instead of testing the code
directly?
...
<tomprince> You should be able to import it just fine.
<_habnabit> str4d, how much code do you have in twisted.plugins?
generally speaking it should be like 1-3 lines of code, which you
can easily put in your tests
<str4d> I can't - Twisted plugins spec defines that twisted/ dir
cannot contain a __init__.py
<str4d> _habnabit: quite a bit of logic
<_habnabit> str4d, sure, but you can put that into your package
without putting it in twisted.plugins
<tomprince> The implementation doesn't need to live in
twisted/plugins. Just enough code to import the implementation
<glyph> str4d: You're talking about too high of a level.  All of
that stuff is fine, the purpose of the modules in the plugin
package is just to *point* at the implementation.  Like, zero lines
of actual code should live there.
<glyph> Just imports, maybe top-level name bindings like
'foo = MyPlugin("foo"); bar = MyPlugin("bar");' possibly.
<glyph> Nothing with indentation ;)
<tomprince> Have a look at the code in the twisted/plugins that
comes with twisted.
<str4d> Perhaps a note about this should be added to
https://twistedmatrix.com/documents/current/core/howto/plugin.html
<str4d> That page specifies only two ways to get at the code:
package in Twisted itself, or place in twisted/plugins/. The latter
is specified as being "primarily useful during development", but a
Twisted noob like myself reads that as "put your IPlugin
implementation there".

trac-id__6816 6816
type__defect defect
reporter__str4d str4d
priority__normal normal
milestone__ 
branch__ 
branch_author__ 
status__new new
resolution__None None
component__core core
keywords__documentation documentation
time__1383782714000000 1383782714000000
changetime__1383782714000000 1383782714000000
version__None None
owner__ 

Start with the Twisted plugin documentation at core/howto/plugin.html and review the existing explanation of plugin package layout and testing. Clarify that plugin logic belongs in the regular package, while twisted/plugins/ should contain only imports or simple bindings to implementations. Done when the page explains this structure and how it makes external plugin logic testable.