[Twisted-Python] Get trial to use the docstring?

[Lucas Taylor]

On 8/5/10 6:25 PM, Nathan wrote:
 > I have a number of questions:
> 
> 1) I found the TreeReporter class that produces the default output
> (twisted/trial/reporter.py), and I found the file that seems to get
> run by trial (twisted/scripts/trial.py) but for the life of me I
> couldn't figure out how to get my own class to show up as one of the
> reporters that you can select by means of the --reporter=whatever
> argument.  How do you tie the two together?  I can just submit my
> modified TreeReporter, but it'd be nice to be able to also submit a
> wildly different option...

Wildly different options sound like a good case for plugins:
http://twistedmatrix.com/documents/current/core/howto/plugin.html

You need to create a plugin that makes your reporter accessible to
Trial. This means it needs to implement the IReporter interface:
http://twistedmatrix.com/documents/10.1.0/api/twisted.trial.itrial.IReporter.html

The plugin should be installed on your PYTHONPATH in a directory named
twisted/plugins. You could just place this in your project for instance,
or in the system twisted/plugins dir.

myproject/twisted/plugins/awesome_reporter.py

The plugin describes the reporter (for --help-reporters) and provides
the importable module and class that gets instantiated.

The reporter itself can be a subclass of TreeReporter or whatever, and
should implement the IReporter interface.

Here is a simple example:
http://gist.github.com/510688

For a much better example, check out the Tahoe-LAFS project
trialcoverage reporter:
http://tahoe-lafs.org/source/trialcoverage/trunk/


> 2) What's the official process for submitting a patch (or where is the
> process documented)?  I've never actually contributed code to
> twisted...

Start here:
http://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs


> 3) Every time I install my custom twisted (with "sudo python setup.py
> install" on OS X 10.6.4 system python), trial starts spitting out the
> "dropin cache" error (see [1] below) which persists until I run "sudo
> twistd --help" as was suggested on the list last week or so.  Isn't
> there some way we can just address that error condition at
> installation time so that doesn't occur in the first place?

"Some way" always comes down to "Someone", which I suspect is a bit like
that ghost the kid from Family Circus is always blaming for muddy
footprints or whatever counts for domestic drama in Bil Keane's
Geritol-addled imagination.

So....there's an existing ticket you could help out with:
http://twistedmatrix.com/trac/ticket/2409

> 4) I'm sold on test-driven development (which is why I'm learning
> trial), so I'd like to both check for regressions and write a test for
> my patch.  I found twisted/trial/test/test_reporter.py -- how do I run
> just the tests in that file?  Does trial run on itself?
> 

Yes.

Trial is pretty flexible about specifying tests to run, so you can run
the whole suite, specify a directory of tests, or point it to a specific
TestCase:

trial twisted
trial twisted/test
trial twisted.test

trial twisted/trial/test/test_reporter.py
trial twisted.trial.test.test_reporter.TestTreeReporter

The same holds for your own project:
trial myproject.tests.test_reporter.AwesomeTreeReporter