id	summary	reporter	owner	description	type	status	priority	milestone	component	resolution	keywords	cc	branch	branch_author	launchpad_bug
3487	Add TestCase.flushWarnings	exarkun		"`TestCase.assertWarns` is limited in that applications can only express a single warning using it.  It is also a somewhat inconvenient API, even for the simplest warning tests, in that it requires filename and line number information which is somewhat confusing to developers.

`TestCase.callDeprecated` is similarly limited.  Additionally, in trying to avoid the confusing API for `assertWarns`, it presents an interface which is very narrow.  Instead of a warning type and message, it takes only a version number.  Additionally, it only works with the `deprecated` decorator, not warnings in general.

This leaves trial without a general tool for making assertions about warnings.  I suggest adding `flushWarnings`.  Trial will collect warnings emitted during the execution of a test.  `flushWarnings` will allow any number of warnings to be cleared from this collection mechanism and returned to the caller.  Any unflushed warnings at the end of a test will be re-emitted so as to be visible to whatever is running trial.  `flushWarnings` will support rudamentary filtering, similar to that offered by `flushLoggedErrors`.

This will work for the use case of multiple warnings.  It removes the possibility for confusing intermediate stack levels to confuse the warning system or the developer.  It gives all available information to the developer so that any assertion may be made.  It preserves reporting of all unexpected or unhandled warnings.  If the filtering supported is based on function objects, it removes the confusing filename/linenumber aspects present in the `assertWarns` API.  Both `assertWarns` and `callDeprecated` can be implemented in terms of this mechanism, as can other higher-level test helpers.

See discussion on #3266 for more details (mostly historic).
"	enhancement	closed	high	Python-2.6	trial	fixed		z3p	branches/flushwarnings-3487	exarkun