New in version 2.1.
Warning messages are typically issued in situations where it is useful to alert the user of
some condition in a program, where that condition (normally) doesn't warrant raising an
exception and terminating the program. For example, one might want to issue a warning when a
program uses an obsolete module.
Python programmers issue warnings by calling the warn() function
defined in this module. (C programmers use PyErr_Warn(); see the Python/C API Reference Manual for details).
Warning messages are normally written to
sys.stderr, but their disposition can
be changed flexibly, from ignoring all warnings to turning them into exceptions. The
disposition of warnings can vary based on the warning category (see below), the text of the
warning message, and the source location where it is issued. Repetitions of a particular
warning for the same source location are typically suppressed.
There are two stages in warning control: first, each time a warning is issued, a
determination is made whether a message should be issued or not; next, if a message is to be
issued, it is formatted and printed using a user-settable hook.
The determination whether to issue a warning message is controlled by the warning filter,
which is a sequence of matching rules and actions. Rules can be added to the filter by calling
filterwarnings() and reset to its default state by calling resetwarnings().
The printing of warning messages is done by calling showwarning(),
which may be overidden; the default implementation of this function formats the message by
calling formatwarning(), which is also available for use by custom