26.4.2 The Warnings Filter

The warnings filter controls whether warnings are ignored, displayed, or turned into errors (raising an exception).

Conceptually, the warnings filter maintains an ordered list of filter specifications; any specific warning is matched against each filter specification in the list in turn until a match is found; the match determines the disposition of the match. Each entry is a tuple of the form (action, message, category, module, lineno), where:

Since the Warning class is derived from the built-in Exception class, to turn a warning into an error we simply raise category(message).

The warnings filter is initialized by -W options passed to the Python interpreter command line. The interpreter saves the arguments for all -W options without interpretation in sys.warnoptions; the warnings module parses these when it is first imported (invalid options are ignored, after printing a message to sys.stderr).

The warnings that are ignored by default may be enabled by passing -Wd to the interpreter. This enables default handling for all warnings, including those that are normally ignored by default. This is particular useful for enabling ImportWarning when debugging problems importing a developed package. ImportWarning can also be enabled explicitly in Python code using:

    warnings.simplefilter('default', ImportWarning)

See About this document... for information on suggesting changes.