1 :mod:`warnings` --- Warning control 2 =================================== 3 4 .. index:: single: warnings 5 6 .. module:: warnings 7 :synopsis: Issue warning messages and control their disposition. 8 9 10 .. versionadded:: 2.1 11 12 **Source code:** :source:`Lib/warnings.py` 13 14 -------------- 15 16 Warning messages are typically issued in situations where it is useful to alert 17 the user of some condition in a program, where that condition (normally) doesn't 18 warrant raising an exception and terminating the program. For example, one 19 might want to issue a warning when a program uses an obsolete module. 20 21 Python programmers issue warnings by calling the :func:`warn` function defined 22 in this module. (C programmers use :c:func:`PyErr_WarnEx`; see 23 :ref:`exceptionhandling` for details). 24 25 Warning messages are normally written to ``sys.stderr``, but their disposition 26 can be changed flexibly, from ignoring all warnings to turning them into 27 exceptions. The disposition of warnings can vary based on the warning category 28 (see below), the text of the warning message, and the source location where it 29 is issued. Repetitions of a particular warning for the same source location are 30 typically suppressed. 31 32 There are two stages in warning control: first, each time a warning is issued, a 33 determination is made whether a message should be issued or not; next, if a 34 message is to be issued, it is formatted and printed using a user-settable hook. 35 36 The determination whether to issue a warning message is controlled by the 37 warning filter, which is a sequence of matching rules and actions. Rules can be 38 added to the filter by calling :func:`filterwarnings` and reset to its default 39 state by calling :func:`resetwarnings`. 40 41 The printing of warning messages is done by calling :func:`showwarning`, which 42 may be overridden; the default implementation of this function formats the 43 message by calling :func:`formatwarning`, which is also available for use by 44 custom implementations. 45 46 .. seealso:: 47 :func:`logging.captureWarnings` allows you to handle all warnings with 48 the standard logging infrastructure. 49 50 51 .. _warning-categories: 52 53 Warning Categories 54 ------------------ 55 56 There are a number of built-in exceptions that represent warning categories. 57 This categorization is useful to be able to filter out groups of warnings. The 58 following warnings category classes are currently defined: 59 60 .. tabularcolumns:: |l|p{0.6\linewidth}| 61 62 +----------------------------------+-----------------------------------------------+ 63 | Class | Description | 64 +==================================+===============================================+ 65 | :exc:`Warning` | This is the base class of all warning | 66 | | category classes. It is a subclass of | 67 | | :exc:`Exception`. | 68 +----------------------------------+-----------------------------------------------+ 69 | :exc:`UserWarning` | The default category for :func:`warn`. | 70 +----------------------------------+-----------------------------------------------+ 71 | :exc:`DeprecationWarning` | Base category for warnings about deprecated | 72 | | features (ignored by default). | 73 +----------------------------------+-----------------------------------------------+ 74 | :exc:`SyntaxWarning` | Base category for warnings about dubious | 75 | | syntactic features. | 76 +----------------------------------+-----------------------------------------------+ 77 | :exc:`RuntimeWarning` | Base category for warnings about dubious | 78 | | runtime features. | 79 +----------------------------------+-----------------------------------------------+ 80 | :exc:`FutureWarning` | Base category for warnings about constructs | 81 | | that will change semantically in the future. | 82 +----------------------------------+-----------------------------------------------+ 83 | :exc:`PendingDeprecationWarning` | Base category for warnings about features | 84 | | that will be deprecated in the future | 85 | | (ignored by default). | 86 +----------------------------------+-----------------------------------------------+ 87 | :exc:`ImportWarning` | Base category for warnings triggered during | 88 | | the process of importing a module (ignored by | 89 | | default). | 90 +----------------------------------+-----------------------------------------------+ 91 | :exc:`UnicodeWarning` | Base category for warnings related to | 92 | | Unicode. | 93 +----------------------------------+-----------------------------------------------+ 94 95 While these are technically built-in exceptions, they are documented here, 96 because conceptually they belong to the warnings mechanism. 97 98 User code can define additional warning categories by subclassing one of the 99 standard warning categories. A warning category must always be a subclass of 100 the :exc:`Warning` class. 101 102 .. versionchanged:: 2.7 103 :exc:`DeprecationWarning` is ignored by default. 104 105 106 .. _warning-filter: 107 108 The Warnings Filter 109 ------------------- 110 111 The warnings filter controls whether warnings are ignored, displayed, or turned 112 into errors (raising an exception). 113 114 Conceptually, the warnings filter maintains an ordered list of filter 115 specifications; any specific warning is matched against each filter 116 specification in the list in turn until a match is found; the match determines 117 the disposition of the match. Each entry is a tuple of the form (*action*, 118 *message*, *category*, *module*, *lineno*), where: 119 120 * *action* is one of the following strings: 121 122 +---------------+----------------------------------------------+ 123 | Value | Disposition | 124 +===============+==============================================+ 125 | ``"error"`` | turn matching warnings into exceptions | 126 +---------------+----------------------------------------------+ 127 | ``"ignore"`` | never print matching warnings | 128 +---------------+----------------------------------------------+ 129 | ``"always"`` | always print matching warnings | 130 +---------------+----------------------------------------------+ 131 | ``"default"`` | print the first occurrence of matching | 132 | | warnings for each location where the warning | 133 | | is issued | 134 +---------------+----------------------------------------------+ 135 | ``"module"`` | print the first occurrence of matching | 136 | | warnings for each module where the warning | 137 | | is issued | 138 +---------------+----------------------------------------------+ 139 | ``"once"`` | print only the first occurrence of matching | 140 | | warnings, regardless of location | 141 +---------------+----------------------------------------------+ 142 143 * *message* is a string containing a regular expression that the start of 144 the warning message must match. The expression is compiled to always be 145 case-insensitive. 146 147 * *category* is a class (a subclass of :exc:`Warning`) of which the warning 148 category must be a subclass in order to match. 149 150 * *module* is a string containing a regular expression that the module name must 151 match. The expression is compiled to be case-sensitive. 152 153 * *lineno* is an integer that the line number where the warning occurred must 154 match, or ``0`` to match all line numbers. 155 156 Since the :exc:`Warning` class is derived from the built-in :exc:`Exception` 157 class, to turn a warning into an error we simply raise ``category(message)``. 158 159 The warnings filter is initialized by :option:`-W` options passed to the Python 160 interpreter command line. The interpreter saves the arguments for all 161 :option:`-W` options without interpretation in ``sys.warnoptions``; the 162 :mod:`warnings` module parses these when it is first imported (invalid options 163 are ignored, after printing a message to ``sys.stderr``). 164 165 166 Default Warning Filters 167 ~~~~~~~~~~~~~~~~~~~~~~~ 168 169 By default, Python installs several warning filters, which can be overridden by 170 the command-line options passed to :option:`-W` and calls to 171 :func:`filterwarnings`. 172 173 * :exc:`DeprecationWarning` and :exc:`PendingDeprecationWarning`, and 174 :exc:`ImportWarning` are ignored. 175 176 * :exc:`BytesWarning` is ignored unless the :option:`-b` option is given once or 177 twice; in this case this warning is either printed (``-b``) or turned into an 178 exception (``-bb``). 179 180 181 .. _warning-suppress: 182 183 Temporarily Suppressing Warnings 184 -------------------------------- 185 186 If you are using code that you know will raise a warning, such as a deprecated 187 function, but do not want to see the warning, then it is possible to suppress 188 the warning using the :class:`catch_warnings` context manager:: 189 190 import warnings 191 192 def fxn(): 193 warnings.warn("deprecated", DeprecationWarning) 194 195 with warnings.catch_warnings(): 196 warnings.simplefilter("ignore") 197 fxn() 198 199 While within the context manager all warnings will simply be ignored. This 200 allows you to use known-deprecated code without having to see the warning while 201 not suppressing the warning for other code that might not be aware of its use 202 of deprecated code. Note: this can only be guaranteed in a single-threaded 203 application. If two or more threads use the :class:`catch_warnings` context 204 manager at the same time, the behavior is undefined. 205 206 207 208 .. _warning-testing: 209 210 Testing Warnings 211 ---------------- 212 213 To test warnings raised by code, use the :class:`catch_warnings` context 214 manager. With it you can temporarily mutate the warnings filter to facilitate 215 your testing. For instance, do the following to capture all raised warnings to 216 check:: 217 218 import warnings 219 220 def fxn(): 221 warnings.warn("deprecated", DeprecationWarning) 222 223 with warnings.catch_warnings(record=True) as w: 224 # Cause all warnings to always be triggered. 225 warnings.simplefilter("always") 226 # Trigger a warning. 227 fxn() 228 # Verify some things 229 assert len(w) == 1 230 assert issubclass(w[-1].category, DeprecationWarning) 231 assert "deprecated" in str(w[-1].message) 232 233 One can also cause all warnings to be exceptions by using ``error`` instead of 234 ``always``. One thing to be aware of is that if a warning has already been 235 raised because of a ``once``/``default`` rule, then no matter what filters are 236 set the warning will not be seen again unless the warnings registry related to 237 the warning has been cleared. 238 239 Once the context manager exits, the warnings filter is restored to its state 240 when the context was entered. This prevents tests from changing the warnings 241 filter in unexpected ways between tests and leading to indeterminate test 242 results. The :func:`showwarning` function in the module is also restored to 243 its original value. Note: this can only be guaranteed in a single-threaded 244 application. If two or more threads use the :class:`catch_warnings` context 245 manager at the same time, the behavior is undefined. 246 247 When testing multiple operations that raise the same kind of warning, it 248 is important to test them in a manner that confirms each operation is raising 249 a new warning (e.g. set warnings to be raised as exceptions and check the 250 operations raise exceptions, check that the length of the warning list 251 continues to increase after each operation, or else delete the previous 252 entries from the warnings list before each new operation). 253 254 255 Updating Code For New Versions of Python 256 ---------------------------------------- 257 258 Warnings that are only of interest to the developer are ignored by default. As 259 such you should make sure to test your code with typically ignored warnings 260 made visible. You can do this from the command-line by passing :option:`-Wd <-W>` 261 to the interpreter (this is shorthand for :option:`!-W default`). This enables 262 default handling for all warnings, including those that are ignored by default. 263 To change what action is taken for encountered warnings you simply change what 264 argument is passed to :option:`-W`, e.g. :option:`!-W error`. See the 265 :option:`-W` flag for more details on what is possible. 266 267 To programmatically do the same as :option:`!-Wd`, use:: 268 269 warnings.simplefilter('default') 270 271 Make sure to execute this code as soon as possible. This prevents the 272 registering of what warnings have been raised from unexpectedly influencing how 273 future warnings are treated. 274 275 Having certain warnings ignored by default is done to prevent a user from 276 seeing warnings that are only of interest to the developer. As you do not 277 necessarily have control over what interpreter a user uses to run their code, 278 it is possible that a new version of Python will be released between your 279 release cycles. The new interpreter release could trigger new warnings in your 280 code that were not there in an older interpreter, e.g. 281 :exc:`DeprecationWarning` for a module that you are using. While you as a 282 developer want to be notified that your code is using a deprecated module, to a 283 user this information is essentially noise and provides no benefit to them. 284 285 286 .. _warning-functions: 287 288 Available Functions 289 ------------------- 290 291 292 .. function:: warn(message[, category[, stacklevel]]) 293 294 Issue a warning, or maybe ignore it or raise an exception. The *category* 295 argument, if given, must be a warning category class (see above); it defaults to 296 :exc:`UserWarning`. Alternatively *message* can be a :exc:`Warning` instance, 297 in which case *category* will be ignored and ``message.__class__`` will be used. 298 In this case the message text will be ``str(message)``. This function raises an 299 exception if the particular warning issued is changed into an error by the 300 warnings filter see above. The *stacklevel* argument can be used by wrapper 301 functions written in Python, like this:: 302 303 def deprecation(message): 304 warnings.warn(message, DeprecationWarning, stacklevel=2) 305 306 This makes the warning refer to :func:`deprecation`'s caller, rather than to the 307 source of :func:`deprecation` itself (since the latter would defeat the purpose 308 of the warning message). 309 310 311 .. function:: warn_explicit(message, category, filename, lineno[, module[, registry[, module_globals]]]) 312 313 This is a low-level interface to the functionality of :func:`warn`, passing in 314 explicitly the message, category, filename and line number, and optionally the 315 module name and the registry (which should be the ``__warningregistry__`` 316 dictionary of the module). The module name defaults to the filename with 317 ``.py`` stripped; if no registry is passed, the warning is never suppressed. 318 *message* must be a string and *category* a subclass of :exc:`Warning` or 319 *message* may be a :exc:`Warning` instance, in which case *category* will be 320 ignored. 321 322 *module_globals*, if supplied, should be the global namespace in use by the code 323 for which the warning is issued. (This argument is used to support displaying 324 source for modules found in zipfiles or other non-filesystem import 325 sources). 326 327 .. versionchanged:: 2.5 328 Added the *module_globals* parameter. 329 330 331 .. function:: warnpy3k(message[, category[, stacklevel]]) 332 333 Issue a warning related to Python 3.x deprecation. Warnings are only shown 334 when Python is started with the -3 option. Like :func:`warn` *message* must 335 be a string and *category* a subclass of :exc:`Warning`. :func:`warnpy3k` 336 is using :exc:`DeprecationWarning` as default warning class. 337 338 .. versionadded:: 2.6 339 340 341 .. function:: showwarning(message, category, filename, lineno[, file[, line]]) 342 343 Write a warning to a file. The default implementation calls 344 ``formatwarning(message, category, filename, lineno, line)`` and writes the 345 resulting string to *file*, which defaults to ``sys.stderr``. You may replace 346 this function with an alternative implementation by assigning to 347 ``warnings.showwarning``. 348 *line* is a line of source code to be included in the warning 349 message; if *line* is not supplied, :func:`showwarning` will 350 try to read the line specified by *filename* and *lineno*. 351 352 .. versionchanged:: 2.7 353 The *line* argument is required to be supported. 354 355 356 .. function:: formatwarning(message, category, filename, lineno[, line]) 357 358 Format a warning the standard way. This returns a string which may contain 359 embedded newlines and ends in a newline. *line* is a line of source code to 360 be included in the warning message; if *line* is not supplied, 361 :func:`formatwarning` will try to read the line specified by *filename* and 362 *lineno*. 363 364 .. versionchanged:: 2.6 365 Added the *line* argument. 366 367 368 .. function:: filterwarnings(action[, message[, category[, module[, lineno[, append]]]]]) 369 370 Insert an entry into the list of :ref:`warnings filter specifications 371 <warning-filter>`. The entry is inserted at the front by default; if 372 *append* is true, it is inserted at the end. This checks the types of the 373 arguments, compiles the *message* and *module* regular expressions, and 374 inserts them as a tuple in the list of warnings filters. Entries closer to 375 the front of the list override entries later in the list, if both match a 376 particular warning. Omitted arguments default to a value that matches 377 everything. 378 379 380 .. function:: simplefilter(action[, category[, lineno[, append]]]) 381 382 Insert a simple entry into the list of :ref:`warnings filter specifications 383 <warning-filter>`. The meaning of the function parameters is as for 384 :func:`filterwarnings`, but regular expressions are not needed as the filter 385 inserted always matches any message in any module as long as the category and 386 line number match. 387 388 389 .. function:: resetwarnings() 390 391 Reset the warnings filter. This discards the effect of all previous calls to 392 :func:`filterwarnings`, including that of the :option:`-W` command line options 393 and calls to :func:`simplefilter`. 394 395 396 Available Context Managers 397 -------------------------- 398 399 .. class:: catch_warnings([\*, record=False, module=None]) 400 401 A context manager that copies and, upon exit, restores the warnings filter 402 and the :func:`showwarning` function. 403 If the *record* argument is :const:`False` (the default) the context manager 404 returns :class:`None` on entry. If *record* is :const:`True`, a list is 405 returned that is progressively populated with objects as seen by a custom 406 :func:`showwarning` function (which also suppresses output to ``sys.stdout``). 407 Each object in the list has attributes with the same names as the arguments to 408 :func:`showwarning`. 409 410 The *module* argument takes a module that will be used instead of the 411 module returned when you import :mod:`warnings` whose filter will be 412 protected. This argument exists primarily for testing the :mod:`warnings` 413 module itself. 414 415 .. note:: 416 417 The :class:`catch_warnings` manager works by replacing and 418 then later restoring the module's 419 :func:`showwarning` function and internal list of filter 420 specifications. This means the context manager is modifying 421 global state and therefore is not thread-safe. 422 423 .. note:: 424 425 In Python 3, the arguments to the constructor for 426 :class:`catch_warnings` are keyword-only arguments. 427 428 .. versionadded:: 2.6 429 430
