Doc/lib/libwarnings.tex

   1 \section{\module{warnings} ---
   2          Warning control}
   3
   4 \declaremodule{standard}{warnings}
   5 \modulesynopsis{Issue warning messages and control their disposition.}
   6 \index{warnings}
   7
   8 \versionadded{2.1}
   9
  10 Warning messages are typically issued in situations where it is useful
  11 to alert the user of some condition in a program, where that condition
  12 (normally) doesn't warrant raising an exception and terminating the
  13 program.  For example, one might want to issue a warning when a
  14 program uses an obsolete module.
  15
  16 Python programmers issue warnings by calling the \function{warn()}
  17 function defined in this module.  (C programmers use
  18 \cfunction{PyErr_Warn()}; see the
  19 \citetitle[../api/exceptionHandling.html]{Python/C API Reference
  20 Manual} for details).
  21
  22 Warning messages are normally written to \code{sys.stderr}, but their
  23 disposition can be changed flexibly, from ignoring all warnings to
  24 turning them into exceptions.  The disposition of warnings can vary
  25 based on the warning category (see below), the text of the warning
  26 message, and the source location where it is issued.  Repetitions of a
  27 particular warning for the same source location are typically
  28 suppressed.
  29
  30 There are two stages in warning control: first, each time a warning is
  31 issued, a determination is made whether a message should be issued or
  32 not; next, if a message is to be issued, it is formatted and printed
  33 using a user-settable hook.
  34
  35 The determination whether to issue a warning message is controlled by
  36 the warning filter, which is a sequence of matching rules and actions.
  37 Rules can be added to the filter by calling
  38 \function{filterwarnings()} and reset to its default state by calling
  39 \function{resetwarnings()}.
  40
  41 The printing of warning messages is done by calling
  42 \function{showwarning()}, which may be overidden; the default
  43 implementation of this function formats the message by calling
  44 \function{formatwarning()}, which is also available for use by custom
  45 implementations.
  46
  47
  48 \subsection{Warning Categories \label{warning-categories}}
  49
  50 There are a number of built-in exceptions that represent warning
  51 categories.  This categorization is useful to be able to filter out
  52 groups of warnings.  The following warnings category classes are
  53 currently defined:
  54
  55 \begin{tableii}{l|l}{exception}{Class}{Description}
  56
  57 \lineii{Warning}{This is the base class of all warning category
  58 classes.  It itself a subclass of Exception.}
  59
  60 \lineii{UserWarning}{The default category for \function{warn()}.}
  61
  62 \lineii{DeprecationWarning}{Base category for warnings about
  63 deprecated features.}
  64
  65 \lineii{SyntaxWarning}{Base category for warnings about dubious
  66 syntactic features.}
  67
  68 \lineii{RuntimeWarning}{Base category for warnings about dubious
  69 runtime features.}
  70
  71 \end{tableii}
  72
  73 While these are technically built-in exceptions, they are documented
  74 here, because conceptually they belong to the warnings mechanism.
  75
  76 User code can define additional warning categories by subclassing one
  77 of the standard warning categories.  A warning category must always be
  78 a subclass of the \exception{Warning} class.
  79
  80
  81 \subsection{The Warnings Filter \label{warning-filter}}
  82
  83 The warnings filter controls whether warnings are ignored, displayed,
  84 or turned into errors (raising an exception).
  85
  86 Conceptually, the warnings filter maintains an ordered list of filter
  87 specifications; any specific warning is matched against each filter
  88 specification in the list in turn until a match is found; the match
  89 determines the disposition of the match.  Each entry is a tuple of the
  90 form (\var{action}, \var{message}, \var{category}, \var{module},
  91 \var{lineno}), where:
  92
  93 \begin{itemize}
  94
  95 \item \var{action} is one of the following strings:
  96
  97     \begin{tableii}{l|l}{code}{Value}{Disposition}
  98
  99     \lineii{"error"}{turn matching warnings into exceptions}
 100
 101     \lineii{"ignore"}{never print matching warnings}
 102
 103     \lineii{"always"}{always print matching warnings}
 104
 105     \lineii{"default"}{print the first occurrence of matching
 106     warnings for each location where the warning is issued}
 107
 108     \lineii{"module"}{print the first occurrence of matching
 109     warnings for each module where the warning is issued}
 110
 111     \lineii{"once"}{print only the first occurrence of matching
 112     warnings, regardless of location}
 113
 114     \end{tableii}
 115
 116 \item \var{message} is a compiled regular expression that the warning
 117 message must match (the match is case-insensitive)
 118
 119 \item \var{category} is a class (a subclass of \exception{Warning}) of
 120       which the warning category must be a subclass in order to match
 121
 122 \item \var{module} is a compiled regular expression that the module
 123       name must match
 124
 125 \item \var{lineno} is an integer that the line number where the
 126       warning occurred must match, or \code{0} to match all line
 127       numbers
 128
 129 \end{itemize}
 130
 131 Since the \exception{Warning} class is derived from the built-in
 132 \exception{Exception} class, to turn a warning into an error we simply
 133 raise \code{category(message)}.
 134
 135 The warnings filter is initialized by \programopt{-W} options passed
 136 to the Python interpreter command line.  The interpreter saves the
 137 arguments for all \programopt{-W} options without interpretation in
 138 \code{sys.warnoptions}; the \module{warnings} module parses these when
 139 it is first imported (invalid options are ignored, after printing a
 140 message to \code{sys.stderr}).
 141
 142
 143 \subsection{Available Functions \label{warning-functions}}
 144
 145 \begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}}
 146 Issue a warning, or maybe ignore it or raise an exception.  The
 147 \var{category} argument, if given, must be a warning category class
 148 (see above); it defaults to \exception{UserWarning}.  This function
 149 raises an exception if the particular warning issued is changed
 150 into an error by the warnings filter see above.  The \var{stacklevel}
 151 argument can be used by wrapper functions written in Python, like
 152 this:
 153
 154 \begin{verbatim}
 155 def deprecation(message):
 156     warnings.warn(message, DeprecationWarning, level=2)
 157 \end{verbatim}
 158
 159 This makes the warning refer to \function{deprecation()}'s caller,
 160 rather than to the source of \function{deprecation()} itself (since
 161 the latter would defeat the purpose of the warning message).
 162 \end{funcdesc}
 163
 164 \begin{funcdesc}{warn_explicit}{message, category, filename,
 165  lineno\optional{, module\optional{, registry}}}
 166 This is a low-level interface to the functionality of
 167 \function{warn()}, passing in explicitly the message, category,
 168 filename and line number, and optionally the module name and the
 169 registry (which should be the \code{__warningregistry__} dictionary of
 170 the module).  The module name defaults to the filename with \code{.py}
 171 stripped; if no registry is passed, the warning is never suppressed.
 172 \end{funcdesc}
 173
 174 \begin{funcdesc}{showwarning}{message, category, filename,
 175                              lineno\optional{, file}}
 176 Write a warning to a file.  The default implementation calls
 177 \code{showwarning(\var{message}, \var{category}, \var{filename},
 178 \var{lineno})} and writes the resulting string to \var{file}, which
 179 defaults to \code{sys.stderr}.  You may replace this function with an
 180 alternative implementation by assigning to
 181 \code{warnings.showwarning}.
 182 \end{funcdesc}
 183
 184 \begin{funcdesc}{formatwarning}{message, category, filename, lineno}
 185 Format a warning the standard way.  This returns a string  which may
 186 contain embedded newlines and ends in a newline.
 187 \end{funcdesc}
 188
 189 \begin{funcdesc}{filterwarnings}{action\optional{,
 190                  message\optional{, category\optional{,
 191                  module\optional{, lineno\optional{, append}}}}}}
 192 Insert an entry into the list of warnings filters.  The entry is
 193 inserted at the front by default; if \var{append} is true, it is
 194 inserted at the end.
 195 This checks the types of the arguments, compiles the message and
 196 module regular expressions, and inserts them as a tuple in front
 197 of the warnings filter.  Entries inserted later override entries
 198 inserted earlier, if both match a particular warning.  Omitted
 199 arguments default to a value that matches everything.
 200 \end{funcdesc}
 201
 202 \begin{funcdesc}{resetwarnings}{}
 203 Reset the warnings filter.  This discards the effect of all previous
 204 calls to \function{filterwarnings()}, including that of the
 205 \programopt{-W} command line options.
 206 \end{funcdesc}