Remove attributes and methods from IReporter that imply text output

[jml]

The following methods should be removed from IReporter:

• write
• writeln
• printErrors
• printSummary

The following attributes should also be removed:

• stream
• separator

We should also consider removing tbformat.

These should be replaced with a single method done(). This method can then be called by a test runner to tell the reporter that the entire test suite has finished running and that it can now summarize results.

Naturally, 'remove' means 'deprecate'.

[jml]

(In [21849]) Branching to 'trial-reporter-done-2883'

[jml]

Ready, I think.

[exarkun]

• twisted/trial/itrial.py: Some docstrings use DEPRECATED, some use Deprecated. Should be easy to pick one or the other.
• twisted/trial/reporter.py
  • New/modified and undocumented and not deprecated on Reporter:
    • startTime
    • startTest
    • addFailure
    • addError
    • _write
    • _writeln
    • _printResults
    • _printErrors
    • _printSummary
  • done's docstring might be improved if it were just a little bit more specific (ie, it writes the summary to its stream and the summary includes the number of tests run and how long they took)
  • MinimalReporter's _printErrors and _printSummary also changed but have no docstrings
  • Lots of methods without docstrings changed on TextReporter
  • Lots of methods without docstrings changed on VerboseTextReporter
  • TimingTextReporter.stopTest has no docstring
  • Changed methods on TreeReporter without docstrings
    • _testPrelude
    • startTest
    • endLine
• twisted/trial/runner.py
  • a warning in TrialRunner.run for the case where done is None, pointing out that the new method should be implemented, would be helpful (ideally this would refer to the location of the definition of the type of the result, but doing that right is probably tricky enough to merit another ticket)
• twisted/trial/test/test_runner.py
  • Test methods changed without docstrings:
    • PyunitTestNames.test_minimalReporter
    • SkipTest.test_summary
    • SkipTest.test_basicErrors
    • SkipTest.test_booleanSkip
    • SkipTest.test_exceptionSkip
  • I think the new deprecation tests really want to be indirecting the call to the deprecated methods by one level (eg, lambda: writeln() instead of writeln) and dropping the stack level down to 2. A utility or more structured way to define deprecations here would certainly be an improvement over this trick and using __file__ with assertWarns.

[jml]

• I've skipped docstrings for VerboseTextReporter and TestReporter. The methods are so similar, so short and so few that they are adequately covered by their class docstrings, interface docstrings and base-class method docstrings.

Otherwise, everything is covered, I think.

[exarkun]

done's docstring misspells occurred as occured.

There's no test for the warning emitted if done is None. Also the stacklevel is probably irrelevant, since there's probably no interesting user-code above the call on the stack.

The rest is good, merge once the above items are fixed.

[jml]

Fixed in [21918].