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 is a subclass of \exception{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 \lineii{FutureWarning}{Base category for warnings about constructs
  72 that will change semantically in the future.}
  73
  74 \end{tableii}
  75
  76 While these are technically built-in exceptions, they are documented
  77 here, because conceptually they belong to the warnings mechanism.
  78
  79 User code can define additional warning categories by subclassing one
  80 of the standard warning categories.  A warning category must always be
  81 a subclass of the \exception{Warning} class.
  82
  83
  84 \subsection{The Warnings Filter \label{warning-filter}}
  85
  86 The warnings filter controls whether warnings are ignored, displayed,
  87 or turned into errors (raising an exception).
  88
  89 Conceptually, the warnings filter maintains an ordered list of filter
  90 specifications; any specific warning is matched against each filter
  91 specification in the list in turn until a match is found; the match
  92 determines the disposition of the match.  Each entry is a tuple of the
  93 form (\var{action}, \var{message}, \var{category}, \var{module},
  94 \var{lineno}), where:
  95
  96 \begin{itemize}
  97
  98 \item \var{action} is one of the following strings:
  99
 100     \begin{tableii}{l|l}{code}{Value}{Disposition}
 101
 102     \lineii{"error"}{turn matching warnings into exceptions}
 103
 104     \lineii{"ignore"}{never print matching warnings}
 105
 106     \lineii{"always"}{always print matching warnings}
 107
 108     \lineii{"default"}{print the first occurrence of matching
 109     warnings for each location where the warning is issued}
 110
 111     \lineii{"module"}{print the first occurrence of matching
 112     warnings for each module where the warning is issued}
 113
 114     \lineii{"once"}{print only the first occurrence of matching
 115     warnings, regardless of location}
 116
 117     \end{tableii}
 118
 119 \item \var{message} is a string containing a regular expression that
 120 the warning message must match (the match is compiled to always be
 121 case-insensitive)
 122
 123 \item \var{category} is a class (a subclass of \exception{Warning}) of
 124       which the warning category must be a subclass in order to match
 125
 126 \item \var{module} is a string containing a regular expression that the module
 127       name must match (the match is compiled to be case-sensitive)
 128
 129 \item \var{lineno} is an integer that the line number where the
 130       warning occurred must match, or \code{0} to match all line
 131       numbers
 132
 133 \end{itemize}
 134
 135 Since the \exception{Warning} class is derived from the built-in
 136 \exception{Exception} class, to turn a warning into an error we simply
 137 raise \code{category(message)}.
 138
 139 The warnings filter is initialized by \programopt{-W} options passed
 140 to the Python interpreter command line.  The interpreter saves the
 141 arguments for all \programopt{-W} options without interpretation in
 142 \code{sys.warnoptions}; the \module{warnings} module parses these when
 143 it is first imported (invalid options are ignored, after printing a
 144 message to \code{sys.stderr}).
 145
 146
 147 \subsection{Available Functions \label{warning-functions}}
 148
 149 \begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}}
 150 Issue a warning, or maybe ignore it or raise an exception.  The
 151 \var{category} argument, if given, must be a warning category class
 152 (see above); it defaults to \exception{UserWarning}.  Alternatively
 153 \var{message} can be a \exception{Warning} instance, in which case
 154 \var{category} will be ignored and \code{message.__class__} will be used.
 155 In this case the message text will be \code{str(message)}. This function
 156 raises an exception if the particular warning issued is changed
 157 into an error by the warnings filter see above.  The \var{stacklevel}
 158 argument can be used by wrapper functions written in Python, like
 159 this:
 160
 161 \begin{verbatim}
 162 def deprecation(message):
 163     warnings.warn(message, DeprecationWarning, stacklevel=2)
 164 \end{verbatim}
 165
 166 This makes the warning refer to \function{deprecation()}'s caller,
 167 rather than to the source of \function{deprecation()} itself (since
 168 the latter would defeat the purpose of the warning message).
 169 \end{funcdesc}
 170
 171 \begin{funcdesc}{warn_explicit}{message, category, filename,
 172  lineno\optional{, module\optional{, registry}}}
 173 This is a low-level interface to the functionality of
 174 \function{warn()}, passing in explicitly the message, category,
 175 filename and line number, and optionally the module name and the
 176 registry (which should be the \code{__warningregistry__} dictionary of
 177 the module).  The module name defaults to the filename with \code{.py}
 178 stripped; if no registry is passed, the warning is never suppressed.
 179 \var{message} must be a string and \var{category} a subclass of
 180 \exception{Warning} or \var{message} may be a \exception{Warning} instance,
 181 in which case \var{category} will be ignored.
 182 \end{funcdesc}
 183
 184 \begin{funcdesc}{showwarning}{message, category, filename,
 185                              lineno\optional{, file}}
 186 Write a warning to a file.  The default implementation calls
 187 \code{formatwarning(\var{message}, \var{category}, \var{filename},
 188 \var{lineno})} and writes the resulting string to \var{file}, which
 189 defaults to \code{sys.stderr}.  You may replace this function with an
 190 alternative implementation by assigning to
 191 \code{warnings.showwarning}.
 192 \end{funcdesc}
 193
 194 \begin{funcdesc}{formatwarning}{message, category, filename, lineno}
 195 Format a warning the standard way.  This returns a string  which may
 196 contain embedded newlines and ends in a newline.
 197 \end{funcdesc}
 198
 199 \begin{funcdesc}{filterwarnings}{action\optional{,
 200                  message\optional{, category\optional{,
 201                  module\optional{, lineno\optional{, append}}}}}}
 202 Insert an entry into the list of warnings filters.  The entry is
 203 inserted at the front by default; if \var{append} is true, it is
 204 inserted at the end.
 205 This checks the types of the arguments, compiles the message and
 206 module regular expressions, and inserts them as a tuple in front
 207 of the warnings filter.  Entries inserted later override entries
 208 inserted earlier, if both match a particular warning.  Omitted
 209 arguments default to a value that matches everything.
 210 \end{funcdesc}
 211
 212 \begin{funcdesc}{resetwarnings}{}
 213 Reset the warnings filter.  This discards the effect of all previous
 214 calls to \function{filterwarnings()}, including that of the
 215 \programopt{-W} command line options.
 216 \end{funcdesc}