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 overridden; the default
implementation of this function formats the message by calling
formatwarning(), which is also available for use by custom
implementations.
