Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 1 | \section{\module{warnings} --- |
| 2 | Warning control} |
| 3 | |
| 4 | \declaremodule{standard}{warnings} |
| 5 | \modulesynopsis{Issue warning messages and control their disposition.} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 6 | \index{warnings} |
| 7 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 8 | \versionadded{2.1} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 18 | \cfunction{PyErr_Warn()}; see the |
| 19 | \citetitle[../api/exceptionHandling.html]{Python/C API Reference |
| 20 | Manual} for details). |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 1dea760 | 2000-12-25 06:19:08 +0000 | [diff] [blame] | 48 | \subsection{Warning Categories \label{warning-categories}} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 55 | \begin{tableii}{l|l}{exception}{Class}{Description} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 56 | |
| 57 | \lineii{Warning}{This is the base class of all warning category |
Fred Drake | ce575ba | 2001-08-14 21:51:50 +0000 | [diff] [blame] | 58 | classes. It is a subclass of \exception{Exception}.} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Barry Warsaw | b8c20a7 | 2002-08-14 16:40:54 +0000 | [diff] [blame] | 71 | \lineii{FutureWarning}{Base category for warnings about constructs |
| 72 | that will change semantically in the future.} |
| 73 | |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 1dea760 | 2000-12-25 06:19:08 +0000 | [diff] [blame] | 84 | \subsection{The Warnings Filter \label{warning-filter}} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 100 | \begin{tableii}{l|l}{code}{Value}{Disposition} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 101 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 102 | \lineii{"error"}{turn matching warnings into exceptions} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 103 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 104 | \lineii{"ignore"}{never print matching warnings} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 105 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 106 | \lineii{"always"}{always print matching warnings} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 107 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 108 | \lineii{"default"}{print the first occurrence of matching |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 109 | warnings for each location where the warning is issued} |
| 110 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 111 | \lineii{"module"}{print the first occurrence of matching |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 112 | warnings for each module where the warning is issued} |
| 113 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 114 | \lineii{"once"}{print only the first occurrence of matching |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 115 | warnings, regardless of location} |
| 116 | |
| 117 | \end{tableii} |
| 118 | |
Andrew M. Kuchling | ba37524 | 2003-02-06 14:38:45 +0000 | [diff] [blame] | 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) |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Andrew M. Kuchling | ba37524 | 2003-02-06 14:38:45 +0000 | [diff] [blame] | 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) |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Fred Drake | 1dea760 | 2000-12-25 06:19:08 +0000 | [diff] [blame] | 147 | \subsection{Available Functions \label{warning-functions}} |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 |
Walter Dörwald | b25c2b0 | 2002-03-21 10:38:40 +0000 | [diff] [blame] | 152 | (see above); it defaults to \exception{UserWarning}. Alternatively |
| 153 | \var{message} can be a \exception{Warning} instance, in which case |
Neal Norwitz | e22d3df | 2002-03-21 12:58:54 +0000 | [diff] [blame] | 154 | \var{category} will be ignored and \code{message.__class__} will be used. |
Walter Dörwald | b25c2b0 | 2002-03-21 10:38:40 +0000 | [diff] [blame] | 155 | In this case the message text will be \code{str(message)}. This function |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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): |
Fred Drake | f981617 | 2002-03-12 19:49:31 +0000 | [diff] [blame] | 163 | warnings.warn(message, DeprecationWarning, stacklevel=2) |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 56ba72a | 2001-02-28 23:34:21 +0000 | [diff] [blame] | 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. |
Walter Dörwald | b25c2b0 | 2002-03-21 10:38:40 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 56ba72a | 2001-02-28 23:34:21 +0000 | [diff] [blame] | 182 | \end{funcdesc} |
| 183 | |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 184 | \begin{funcdesc}{showwarning}{message, category, filename, |
| 185 | lineno\optional{, file}} |
| 186 | Write a warning to a file. The default implementation calls |
Tim Peters | 93ceaea | 2003-07-01 14:37:59 +0000 | [diff] [blame] | 187 | \code{formatwarning(\var{message}, \var{category}, \var{filename}, |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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{, |
Fred Drake | 1dea760 | 2000-12-25 06:19:08 +0000 | [diff] [blame] | 200 | message\optional{, category\optional{, |
Guido van Rossum | 77b20f0 | 2001-01-14 14:10:18 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 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 |
Fred Drake | 288927f | 2001-01-04 05:59:37 +0000 | [diff] [blame] | 214 | calls to \function{filterwarnings()}, including that of the |
| 215 | \programopt{-W} command line options. |
Guido van Rossum | 5db5ba1 | 2000-12-19 06:01:23 +0000 | [diff] [blame] | 216 | \end{funcdesc} |