[Twisted-Python] Removing _wait from Trial

[Jonathan Lange]

So, I would like to remove _wait() from Trial and make it work like a
regular Twisted application. I've had all this stuff on my brain, and
have decided to dump it here for feedback. Here's how the plan looks
at the moment[1]:


1. Deprecate the use of reactor-spinning things within tests. (Twisted 2.5)

We've already done a great deal of work on this. spinWhile, spinUntil
and util.wait have alll been deprecated and removed.

#2090 (ready for review) actually issues deprecation warnings when the
reactor is iterated, crashed or stopped within a test.

Unfortunately, some of Trial's cleanup code spins the reactor (see
t.trial.util._Janitor.do_cleanPending). This has to go.


2. Tighten test cleanup errors. (Twisted 2.5)

#2091 (ready for review) fulfils a long-standing promise. The "reactor
unclean" warnings have been turned into errors. It doesn't help us
remove _wait, but

To remove _wait, we'll also have to remove the two calls to
reactor.iterate() from _Janitor (see #2092). That means that many
tests that *thought* they were cleaning up the reactor properly will
find out that they weren't. We can reduce the number of errors by
simulating reactor.iterate() using callLater. However, experiments
show that even with this bandaid, there will still be new errors in
the Twisted suite.

That means we will have to either:
a) surprise our users with new errors in their tests
b) find some way to introduce this gradually.

Obviously everyone[2] would prefer b). I've filed #2124 explaining how
that might work.


3. Introduce asynchronous APIs to Trial (Twisted 2.6)

Currently TestCase.run() is a blocking call. I wish it could remain a
blocking call, but it can't.

The branch for #1781 makes a SyncTestCase and an AsyncTestCase. run()
works in SyncTestCase and doesn't work in AsyncTestCase. For
AsyncTestCase, one uses runDeferred().

Although the branch for #1781 will need to be abandoned, these new
classes should be brought in for Twisted 2.6 (without breaking run()).
Naturally, this affects many, many tests in Trial.

We might even add runDeferred to TestSuite at this point.


4. Deprecate TestSuite.run and TestCase.run. (Twisted 2.6)

Neither of these will work without wait[3] and they are both public
APIs. Also remove the calls to iterate() from _Janitor at this point.


5. Actually remove _wait. (Twisted 2.7)

Add runDeferred() to TestSuite, make run() raise NotImplementedErrors
for TestCase and TestSuite. Alter TrialSuite to start and stop the
reactor.

I can't find a theory to explain why this change will break unexpected
tests in the Twisted suite. However, it will certainly happen. That
means that some tests in user code will probably break as well. I
don't know how we could make this any smoother.


Questions:
- What should I do with the ticket #1781?
- What should I do with the branch for #1781?
- What more can we do to reduce the number of tests that will break
when _wait is removed?
- Thoughts?

thanks for getting this far :),
jml

[1] Incidentally, all of this would be superfluous if reactors were restartable.
[2] Well, almost everyone
[3] ... or restartable reactors.