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