| .. versionadded:: 2.1 |
| |
| Warning messages are typically issued in situations where it is useful to alert |
| the user of some condition in a program, where that condition (normally) doesn't |
| warrant raising an exception and terminating the program. For example, one |
| might want to issue a warning when a program uses an obsolete module. |
| |
| Python programmers issue warnings by calling the :func:`warn` function defined |
n | in this module. (C programmers use :cfunc:`PyErr_Warn`; see the Python/C API |
n | in this module. (C programmers use :cfunc:`PyErr_WarnEx`; see |
| Reference Manual (XXX reference: ../api/exceptionHandling.html) for details). |
| :ref:`exceptionhandling` for details). |
| |
| Warning messages are normally written to ``sys.stderr``, but their disposition |
| can be changed flexibly, from ignoring all warnings to turning them into |
| exceptions. The disposition of warnings can vary based on the warning category |
| (see below), the text of the warning message, and the source location where it |
| is issued. Repetitions of a particular warning for the same source location are |
| typically suppressed. |
| |
| |
| The warnings that are ignored by default may be enabled by passing :option:`-Wd` |
| to the interpreter. This enables default handling for all warnings, including |
| those that are normally ignored by default. This is particular useful for |
| enabling ImportWarning when debugging problems importing a developed package. |
| ImportWarning can also be enabled explicitly in Python code using:: |
| |
| warnings.simplefilter('default', ImportWarning) |
n | |
| |
| .. _warning-suppress: |
| |
| Temporarily Suppressing Warnings |
| -------------------------------- |
| |
| If you are using code that you know will raise a warning, such as a deprecated |
| function, but do not want to see the warning, then it is possible to suppress |
| the warning using the :class:`catch_warnings` context manager:: |
| |
| import warnings |
| |
| def fxn(): |
| warnings.warn("deprecated", DeprecationWarning) |
| |
| with warnings.catch_warnings(): |
| warnings.simplefilter("ignore") |
| fxn() |
| |
| While within the context manager all warnings will simply be ignored. This |
| allows you to use known-deprecated code without having to see the warning while |
| not suppressing the warning for other code that might not be aware of its use |
| of deprecated code. |
| |
| |
| .. _warning-testing: |
| |
| Testing Warnings |
| ---------------- |
| |
| To test warnings raised by code, use the :class:`catch_warnings` context |
| manager. With it you can temporarily mutate the warnings filter to facilitate |
| your testing. For instance, do the following to capture all raised warnings to |
| check:: |
| |
| import warnings |
| |
| def fxn(): |
| warnings.warn("deprecated", DeprecationWarning) |
| |
| with warnings.catch_warnings(record=True) as w: |
| # Cause all warnings to always be triggered. |
| warnings.simplefilter("always") |
| # Trigger a warning. |
| fxn() |
| # Verify some things |
| assert len(w) == 1 |
| assert isinstance(w[-1].category, DeprecationWarning) |
| assert "deprecated" in str(w[-1].message) |
| |
| One can also cause all warnings to be exceptions by using ``error`` instead of |
| ``always``. One thing to be aware of is that if a warning has already been |
| raised because of a ``once``/``default`` rule, then no matter what filters are |
| set the warning will not be seen again unless the warnings registry related to |
| the warning has been cleared. |
| |
| Once the context manager exits, the warnings filter is restored to its state |
| when the context was entered. This prevents tests from changing the warnings |
| filter in unexpected ways between tests and leading to indeterminate test |
| results. The :func:`showwarning` function in the module is also restored to |
| its original value. |
| |
| When testing multiple operations that raise the same kind of warning, it |
| is important to test them in a manner that confirms each operation is raising |
| a new warning (e.g. set warnings to be raised as exceptions and check the |
| operations raise exceptions, check that the length of the warning list |
| continues to increase after each operation, or else delete the previous |
| entries from the warnings list before each new operation). |
| |
| |
| .. _warning-functions: |
| |
| Available Functions |
| ------------------- |
| |
| |
| dictionary of the module). The module name defaults to the filename with |
| ``.py`` stripped; if no registry is passed, the warning is never suppressed. |
| *message* must be a string and *category* a subclass of :exc:`Warning` or |
| *message* may be a :exc:`Warning` instance, in which case *category* will be |
| ignored. |
| |
| *module_globals*, if supplied, should be the global namespace in use by the code |
| for which the warning is issued. (This argument is used to support displaying |
n | source for modules found in zipfiles or other non-filesystem import sources, and |
n | source for modules found in zipfiles or other non-filesystem import |
| was added in Python 2.5.) |
| sources). |
| |
n | .. versionchanged:: 2.5 |
| Added the *module_globals* parameter. |
| |
n | |
| .. function:: warnpy3k(message[, category[, stacklevel]]) |
| |
| Issue a warning related to Python 3.x deprecation. Warnings are only shown |
| when Python is started with the -3 option. Like :func:`warn` *message* must |
| be a string and *category* a subclass of :exc:`Warning`. :func:`warnpy3k` |
| is using :exc:`DeprecationWarning` as default warning class. |
| |
| |
| .. function:: showwarning(message, category, filename, lineno[, file]) |
| .. function:: showwarning(message, category, filename, lineno[, file[, line]]) |
| |
| Write a warning to a file. The default implementation calls |
n | ``formatwarning(message, category, filename, lineno)`` and writes the resulting |
n | ``formatwarning(message, category, filename, lineno, line)`` and writes the |
| string to *file*, which defaults to ``sys.stderr``. You may replace this |
| resulting string to *file*, which defaults to ``sys.stderr``. You may replace |
| function with an alternative implementation by assigning to |
| this function with an alternative implementation by assigning to |
| ``warnings.showwarning``. |
n | *line* is a line of source code to be included in the warning |
| message; if *line* is not supplied, :func:`showwarning` will |
| try to read the line specified by *filename* and *lineno*. |
| |
n | .. versionchanged:: 2.6 |
| Added the *line* argument. Implementations that lack the new argument |
| will trigger a :exc:`DeprecationWarning`. |
| |
n | |
| .. function:: formatwarning(message, category, filename, lineno) |
| .. function:: formatwarning(message, category, filename, lineno[, line]) |
| |
| Format a warning the standard way. This returns a string which may contain |
n | embedded newlines and ends in a newline. |
n | embedded newlines and ends in a newline. *line* is |
| a line of source code to be included in the warning message; if *line* is not supplied, |
| :func:`formatwarning` will try to read the line specified by *filename* and *lineno*. |
| |
| .. versionchanged:: 2.6 |
| Added the *line* argument. |
| |
| |
| .. function:: filterwarnings(action[, message[, category[, module[, lineno[, append]]]]]) |
| |
| Insert an entry into the list of warnings filters. The entry is inserted at the |
| front by default; if *append* is true, it is inserted at the end. This checks |
| the types of the arguments, compiles the message and module regular expressions, |
| and inserts them as a tuple in the list of warnings filters. Entries closer to |
| |
| |
| .. function:: resetwarnings() |
| |
| Reset the warnings filter. This discards the effect of all previous calls to |
| :func:`filterwarnings`, including that of the :option:`-W` command line options |
| and calls to :func:`simplefilter`. |
| |
t | |
| Available Context Managers |
| -------------------------- |
| |
| .. class:: catch_warnings([\*, record=False, module=None]) |
| |
| A context manager that copies and, upon exit, restores the warnings filter |
| and the :func:`showwarning` function. |
| If the *record* argument is :const:`False` (the default) the context manager |
| returns :class:`None` on entry. If *record* is :const:`True`, a list is |
| returned that is progressively populated with objects as seen by a custom |
| :func:`showwarning` function (which also suppresses output to ``sys.stdout``). |
| Each object in the list has attributes with the same names as the arguments to |
| :func:`showwarning`. |
| |
| The *module* argument takes a module that will be used instead of the |
| module returned when you import :mod:`warnings` whose filter will be |
| protected. This argument exists primarily for testing the :mod:`warnings` |
| module itself. |
| |
| .. note:: |
| |
| In Python 3.0, the arguments to the constructor for |
| :class:`catch_warnings` are keyword-only arguments. |
| |
| .. versionadded:: 2.6 |
| |