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. 55 56 While these are technically 57 :ref:`built-in exceptions <warning-categories-as-exceptions>`, they are 58 documented here, because conceptually they belong to the warnings mechanism. 59 60 User code can define additional warning categories by subclassing one of the 61 standard warning categories. A warning category must always be a subclass of 62 the :exc:`Warning` class. 63 64 The following warnings category classes are currently defined: 65 66 .. tabularcolumns:: |l|p{0.6\linewidth}| 67 68 +----------------------------------+-----------------------------------------------+ 69 | Class | Description | 70 +==================================+===============================================+ 71 | :exc:`Warning` | This is the base class of all warning | 72 | | category classes. It is a subclass of | 73 | | :exc:`Exception`. | 74 +----------------------------------+-----------------------------------------------+ 75 | :exc:`UserWarning` | The default category for :func:`warn`. | 76 +----------------------------------+-----------------------------------------------+ 77 | :exc:`DeprecationWarning` | Base category for warnings about deprecated | 78 | | features when those warnings are intended for | 79 | | other Python developers (ignored by default, | 80 | | unless triggered by code in ``__main__``). | 81 +----------------------------------+-----------------------------------------------+ 82 | :exc:`SyntaxWarning` | Base category for warnings about dubious | 83 | | syntactic features. | 84 +----------------------------------+-----------------------------------------------+ 85 | :exc:`RuntimeWarning` | Base category for warnings about dubious | 86 | | runtime features. | 87 +----------------------------------+-----------------------------------------------+ 88 | :exc:`FutureWarning` | Base category for warnings about deprecated | 89 | | features when those warnings are intended for | 90 | | end users of applications that are written in | 91 | | Python. | 92 +----------------------------------+-----------------------------------------------+ 93 | :exc:`PendingDeprecationWarning` | Base category for warnings about features | 94 | | that will be deprecated in the future | 95 | | (ignored by default). | 96 +----------------------------------+-----------------------------------------------+ 97 | :exc:`ImportWarning` | Base category for warnings triggered during | 98 | | the process of importing a module (ignored by | 99 | | default). | 100 +----------------------------------+-----------------------------------------------+ 101 | :exc:`UnicodeWarning` | Base category for warnings related to | 102 | | Unicode. | 103 +----------------------------------+-----------------------------------------------+ 104 | :exc:`BytesWarning` | Base category for warnings related to | 105 | | :class:`bytes` and :class:`bytearray`. | 106 +----------------------------------+-----------------------------------------------+ 107 | :exc:`ResourceWarning` | Base category for warnings related to | 108 | | resource usage. | 109 +----------------------------------+-----------------------------------------------+ 110 111 .. versionchanged:: 3.7 112 Previously :exc:`DeprecationWarning` and :exc:`FutureWarning` were 113 distinguished based on whether a feature was being removed entirely or 114 changing its behaviour. They are now distinguished based on their 115 intended audience and the way they're handled by the default warnings 116 filters. 117 118 119 .. _warning-filter: 120 121 The Warnings Filter 122 ------------------- 123 124 The warnings filter controls whether warnings are ignored, displayed, or turned 125 into errors (raising an exception). 126 127 Conceptually, the warnings filter maintains an ordered list of filter 128 specifications; any specific warning is matched against each filter 129 specification in the list in turn until a match is found; the filter determines 130 the disposition of the match. Each entry is a tuple of the form (*action*, 131 *message*, *category*, *module*, *lineno*), where: 132 133 * *action* is one of the following strings: 134 135 +---------------+----------------------------------------------+ 136 | Value | Disposition | 137 +===============+==============================================+ 138 | ``"default"`` | print the first occurrence of matching | 139 | | warnings for each location (module + | 140 | | line number) where the warning is issued | 141 +---------------+----------------------------------------------+ 142 | ``"error"`` | turn matching warnings into exceptions | 143 +---------------+----------------------------------------------+ 144 | ``"ignore"`` | never print matching warnings | 145 +---------------+----------------------------------------------+ 146 | ``"always"`` | always print matching warnings | 147 +---------------+----------------------------------------------+ 148 | ``"module"`` | print the first occurrence of matching | 149 | | warnings for each module where the warning | 150 | | is issued (regardless of line number) | 151 +---------------+----------------------------------------------+ 152 | ``"once"`` | print only the first occurrence of matching | 153 | | warnings, regardless of location | 154 +---------------+----------------------------------------------+ 155 156 * *message* is a string containing a regular expression that the start of 157 the warning message must match. The expression is compiled to always be 158 case-insensitive. 159 160 * *category* is a class (a subclass of :exc:`Warning`) of which the warning 161 category must be a subclass in order to match. 162 163 * *module* is a string containing a regular expression that the module name must 164 match. The expression is compiled to be case-sensitive. 165 166 * *lineno* is an integer that the line number where the warning occurred must 167 match, or ``0`` to match all line numbers. 168 169 Since the :exc:`Warning` class is derived from the built-in :exc:`Exception` 170 class, to turn a warning into an error we simply raise ``category(message)``. 171 172 If a warning is reported and doesn't match any registered filter then the 173 "default" action is applied (hence its name). 174 175 176 .. _describing-warning-filters: 177 178 Describing Warning Filters 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 180 181 The warnings filter is initialized by :option:`-W` options passed to the Python 182 interpreter command line and the :envvar:`PYTHONWARNINGS` environment variable. 183 The interpreter saves the arguments for all supplied entries without 184 interpretation in ``sys.warnoptions``; the :mod:`warnings` module parses these 185 when it is first imported (invalid options are ignored, after printing a 186 message to ``sys.stderr``). 187 188 Individual warnings filters are specified as a sequence of fields separated by 189 colons:: 190 191 action:message:category:module:line 192 193 The meaning of each of these fields is as described in :ref:`warning-filter`. 194 When listing multiple filters on a single line (as for 195 :envvar:`PYTHONWARNINGS`), the individual filters are separated by commas,and 196 the filters listed later take precedence over those listed before them (as 197 they're applied left-to-right, and the most recently applied filters take 198 precedence over earlier ones). 199 200 Commonly used warning filters apply to either all warnings, warnings in a 201 particular category, or warnings raised by particular modules or packages. 202 Some examples:: 203 204 default # Show all warnings (even those ignored by default) 205 ignore # Ignore all warnings 206 error # Convert all warnings to errors 207 error::ResourceWarning # Treat ResourceWarning messages as errors 208 default::DeprecationWarning # Show DeprecationWarning messages 209 ignore,default:::mymodule # Only report warnings triggered by "mymodule" 210 error:::mymodule[.*] # Convert warnings to errors in "mymodule" 211 # and any subpackages of "mymodule" 212 213 214 .. _default-warning-filter: 215 216 Default Warning Filter 217 ~~~~~~~~~~~~~~~~~~~~~~ 218 219 By default, Python installs several warning filters, which can be overridden by 220 the :option:`-W` command-line option, the :envvar:`PYTHONWARNINGS` environment 221 variable and calls to :func:`filterwarnings`. 222 223 In regular release builds, the default warning filter has the following entries 224 (in order of precedence):: 225 226 default::DeprecationWarning:__main__ 227 ignore::DeprecationWarning 228 ignore::PendingDeprecationWarning 229 ignore::ImportWarning 230 ignore::ResourceWarning 231 232 In debug builds, the list of default warning filters is empty. 233 234 .. versionchanged:: 3.2 235 :exc:`DeprecationWarning` is now ignored by default in addition to 236 :exc:`PendingDeprecationWarning`. 237 238 .. versionchanged:: 3.7 239 :exc:`DeprecationWarning` is once again shown by default when triggered 240 directly by code in ``__main__``. 241 242 .. versionchanged:: 3.7 243 :exc:`BytesWarning` no longer appears in the default filter list and is 244 instead configured via :data:`sys.warnoptions` when :option:`-b` is specified 245 twice. 246 247 248 .. _warning-disable: 249 250 Overriding the default filter 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 252 253 Developers of applications written in Python may wish to hide *all* Python level 254 warnings from their users by default, and only display them when running tests 255 or otherwise working on the application. The :data:`sys.warnoptions` attribute 256 used to pass filter configurations to the interpreter can be used as a marker to 257 indicate whether or not warnings should be disabled:: 258 259 import sys 260 261 if not sys.warnoptions: 262 import warnings 263 warnings.simplefilter("ignore") 264 265 Developers of test runners for Python code are advised to instead ensure that 266 *all* warnings are displayed by default for the code under test, using code 267 like:: 268 269 import sys 270 271 if not sys.warnoptions: 272 import os, warnings 273 warnings.simplefilter("default") # Change the filter in this process 274 os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses 275 276 Finally, developers of interactive shells that run user code in a namespace 277 other than ``__main__`` are advised to ensure that :exc:`DeprecationWarning` 278 messages are made visible by default, using code like the following (where 279 ``user_ns`` is the module used to execute code entered interactively):: 280 281 import warnings 282 warnings.filterwarnings("default", category=DeprecationWarning, 283 module=user_ns.get("__name__")) 284 285 286 .. _warning-suppress: 287 288 Temporarily Suppressing Warnings 289 -------------------------------- 290 291 If you are using code that you know will raise a warning, such as a deprecated 292 function, but do not want to see the warning (even when warnings have been 293 explicitly configured via the command line), then it is possible to suppress 294 the warning using the :class:`catch_warnings` context manager:: 295 296 import warnings 297 298 def fxn(): 299 warnings.warn("deprecated", DeprecationWarning) 300 301 with warnings.catch_warnings(): 302 warnings.simplefilter("ignore") 303 fxn() 304 305 While within the context manager all warnings will simply be ignored. This 306 allows you to use known-deprecated code without having to see the warning while 307 not suppressing the warning for other code that might not be aware of its use 308 of deprecated code. Note: this can only be guaranteed in a single-threaded 309 application. If two or more threads use the :class:`catch_warnings` context 310 manager at the same time, the behavior is undefined. 311 312 313 314 .. _warning-testing: 315 316 Testing Warnings 317 ---------------- 318 319 To test warnings raised by code, use the :class:`catch_warnings` context 320 manager. With it you can temporarily mutate the warnings filter to facilitate 321 your testing. For instance, do the following to capture all raised warnings to 322 check:: 323 324 import warnings 325 326 def fxn(): 327 warnings.warn("deprecated", DeprecationWarning) 328 329 with warnings.catch_warnings(record=True) as w: 330 # Cause all warnings to always be triggered. 331 warnings.simplefilter("always") 332 # Trigger a warning. 333 fxn() 334 # Verify some things 335 assert len(w) == 1 336 assert issubclass(w[-1].category, DeprecationWarning) 337 assert "deprecated" in str(w[-1].message) 338 339 One can also cause all warnings to be exceptions by using ``error`` instead of 340 ``always``. One thing to be aware of is that if a warning has already been 341 raised because of a ``once``/``default`` rule, then no matter what filters are 342 set the warning will not be seen again unless the warnings registry related to 343 the warning has been cleared. 344 345 Once the context manager exits, the warnings filter is restored to its state 346 when the context was entered. This prevents tests from changing the warnings 347 filter in unexpected ways between tests and leading to indeterminate test 348 results. The :func:`showwarning` function in the module is also restored to 349 its original value. Note: this can only be guaranteed in a single-threaded 350 application. If two or more threads use the :class:`catch_warnings` context 351 manager at the same time, the behavior is undefined. 352 353 When testing multiple operations that raise the same kind of warning, it 354 is important to test them in a manner that confirms each operation is raising 355 a new warning (e.g. set warnings to be raised as exceptions and check the 356 operations raise exceptions, check that the length of the warning list 357 continues to increase after each operation, or else delete the previous 358 entries from the warnings list before each new operation). 359 360 361 .. _warning-ignored: 362 363 Updating Code For New Versions of Dependencies 364 ---------------------------------------------- 365 366 Warning categories that are primarily of interest to Python developers (rather 367 than end users of applications written in Python) are ignored by default. 368 369 Notably, this "ignored by default" list includes :exc:`DeprecationWarning` 370 (for every module except ``__main__``), which means developers should make sure 371 to test their code with typically ignored warnings made visible in order to 372 receive timely notifications of future breaking API changes (whether in the 373 standard library or third party packages). 374 375 In the ideal case, the code will have a suitable test suite, and the test runner 376 will take care of implicitly enabling all warnings when running tests 377 (the test runner provided by the :mod:`unittest` module does this). 378 379 In less ideal cases, applications can be checked for use of deprecated 380 interfaces by passing :option:`-Wd <-W>` to the Python interpreter (this is 381 shorthand for :option:`!-W default`) or setting ``PYTHONWARNINGS=default`` in 382 the environment. This enables default handling for all warnings, including those 383 that are ignored by default. To change what action is taken for encountered 384 warnings you can change what argument is passed to :option:`-W` (e.g. 385 :option:`!-W error`). See the :option:`-W` flag for more details on what is 386 possible. 387 388 389 .. _warning-functions: 390 391 Available Functions 392 ------------------- 393 394 395 .. function:: warn(message, category=None, stacklevel=1, source=None) 396 397 Issue a warning, or maybe ignore it or raise an exception. The *category* 398 argument, if given, must be a warning category class (see above); it defaults to 399 :exc:`UserWarning`. Alternatively *message* can be a :exc:`Warning` instance, 400 in which case *category* will be ignored and ``message.__class__`` will be used. 401 In this case the message text will be ``str(message)``. This function raises an 402 exception if the particular warning issued is changed into an error by the 403 warnings filter see above. The *stacklevel* argument can be used by wrapper 404 functions written in Python, like this:: 405 406 def deprecation(message): 407 warnings.warn(message, DeprecationWarning, stacklevel=2) 408 409 This makes the warning refer to :func:`deprecation`'s caller, rather than to the 410 source of :func:`deprecation` itself (since the latter would defeat the purpose 411 of the warning message). 412 413 *source*, if supplied, is the destroyed object which emitted a 414 :exc:`ResourceWarning`. 415 416 .. versionchanged:: 3.6 417 Added *source* parameter. 418 419 420 .. function:: warn_explicit(message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None) 421 422 This is a low-level interface to the functionality of :func:`warn`, passing in 423 explicitly the message, category, filename and line number, and optionally the 424 module name and the registry (which should be the ``__warningregistry__`` 425 dictionary of the module). The module name defaults to the filename with 426 ``.py`` stripped; if no registry is passed, the warning is never suppressed. 427 *message* must be a string and *category* a subclass of :exc:`Warning` or 428 *message* may be a :exc:`Warning` instance, in which case *category* will be 429 ignored. 430 431 *module_globals*, if supplied, should be the global namespace in use by the code 432 for which the warning is issued. (This argument is used to support displaying 433 source for modules found in zipfiles or other non-filesystem import 434 sources). 435 436 *source*, if supplied, is the destroyed object which emitted a 437 :exc:`ResourceWarning`. 438 439 .. versionchanged:: 3.6 440 Add the *source* parameter. 441 442 443 .. function:: showwarning(message, category, filename, lineno, file=None, line=None) 444 445 Write a warning to a file. The default implementation calls 446 ``formatwarning(message, category, filename, lineno, line)`` and writes the 447 resulting string to *file*, which defaults to ``sys.stderr``. You may replace 448 this function with any callable by assigning to ``warnings.showwarning``. 449 *line* is a line of source code to be included in the warning 450 message; if *line* is not supplied, :func:`showwarning` will 451 try to read the line specified by *filename* and *lineno*. 452 453 454 .. function:: formatwarning(message, category, filename, lineno, line=None) 455 456 Format a warning the standard way. This returns a string which may contain 457 embedded newlines and ends in a newline. *line* is a line of source code to 458 be included in the warning message; if *line* is not supplied, 459 :func:`formatwarning` will try to read the line specified by *filename* and 460 *lineno*. 461 462 463 .. function:: filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False) 464 465 Insert an entry into the list of :ref:`warnings filter specifications 466 <warning-filter>`. The entry is inserted at the front by default; if 467 *append* is true, it is inserted at the end. This checks the types of the 468 arguments, compiles the *message* and *module* regular expressions, and 469 inserts them as a tuple in the list of warnings filters. Entries closer to 470 the front of the list override entries later in the list, if both match a 471 particular warning. Omitted arguments default to a value that matches 472 everything. 473 474 475 .. function:: simplefilter(action, category=Warning, lineno=0, append=False) 476 477 Insert a simple entry into the list of :ref:`warnings filter specifications 478 <warning-filter>`. The meaning of the function parameters is as for 479 :func:`filterwarnings`, but regular expressions are not needed as the filter 480 inserted always matches any message in any module as long as the category and 481 line number match. 482 483 484 .. function:: resetwarnings() 485 486 Reset the warnings filter. This discards the effect of all previous calls to 487 :func:`filterwarnings`, including that of the :option:`-W` command line options 488 and calls to :func:`simplefilter`. 489 490 491 Available Context Managers 492 -------------------------- 493 494 .. class:: catch_warnings(\*, record=False, module=None) 495 496 A context manager that copies and, upon exit, restores the warnings filter 497 and the :func:`showwarning` function. 498 If the *record* argument is :const:`False` (the default) the context manager 499 returns :class:`None` on entry. If *record* is :const:`True`, a list is 500 returned that is progressively populated with objects as seen by a custom 501 :func:`showwarning` function (which also suppresses output to ``sys.stdout``). 502 Each object in the list has attributes with the same names as the arguments to 503 :func:`showwarning`. 504 505 The *module* argument takes a module that will be used instead of the 506 module returned when you import :mod:`warnings` whose filter will be 507 protected. This argument exists primarily for testing the :mod:`warnings` 508 module itself. 509 510 .. note:: 511 512 The :class:`catch_warnings` manager works by replacing and 513 then later restoring the module's 514 :func:`showwarning` function and internal list of filter 515 specifications. This means the context manager is modifying 516 global state and therefore is not thread-safe. 517
