On Thu, Sep 4, 2008 at 4:18 PM, Glyph Lefkowitz <report@bugs.python.org> wrote:
>
> Glyph Lefkowitz <glyph@divmod.com> added the comment:
>
> The use of the term "filter" is pretty confusing.  I would normally say
> it was just me, but a bunch of other Twisted hackers seemed to interpret
> it the same way: a "filter" is something that has an opportunity to
> remove something else.  For example, the python builtin function
> "filter".  Experimentation with the filters list seems to confirm this
> impression, since later filters do not have an opportunity to access the
> warnings that earlier filters have removed.  The intuitive leap there is
> to assume that inserting a filter at the head of the list won't do
> anything different than inserting it at the tail, since a later filter
> will remove it.
>

OK, so you were thinking of the filter list in a functional sense
where exceptions are passed down the chain to each filter rule instead
of a bunch of tests that stop checking once one of the rules applies.

> I can't think of an obvious recommendation to improve the text for the
> filter system itself, because upon reading it in more depth, it's fairly
> clear.  Maybe the heading could be changed to something more like
> "intercepting warnings" or "controlling the way that warnings are
> emitted"?  Something attention-grabbing that describes its purpose and
> doesn't use the word "filter".  Even a sub-heading which simply
> described how to use 'always'   filter to cause every warning to be
> emitted would be helpful.
>

OK.

> The biggest improvement to the documentation for "catch_warnings" would
> be to put it in a section of its own, "How To Test Your Code Which Uses
> Warnings", not as a footnote in "Available Classes".
>

Fair enough.

> (Also, as a minor note to be taken at your discretion: should
> catch_warnings be named PEP 8 style as a class, since it is one?  I
> don't really want to open that can of worms after reading the
> interminable threading.Event thread, but it seemed worth saying as long
> as was talking about this...)

It's partially historical since test.test_support.catch_warning() is a
context manager created from a generator. But it's also because I want
to have the option to change the context manager in the future if the
bootstrapping reasons that led to it being a class can go away. I
should probably change the section title to "Available Context
Managers" so people don't start making assumptions.

-Brett