How to use Python Warnings Framework?

Warnings are issued when future language changes might break existing code in a future python release. Warnings are ideally used in the places where the condition or usage doesn’t raise any exception or terminating the program. For example, Warnings can be used to indicate that user is using an obsolete module. Warnings can be configured to print messages, raise exceptions.

If you are library developer or you develop modules that are consumed by other people, warnings are the graceful way to add, remove or modify the behavior of the module. Warnings module is a part of standard python library. So we do not have to install it sep

Enable/Disable Warning Filter using commandline

Warning messages can be controlled globally using the -W option to the interpreter. While running python your script pass the argument -W to the interpreter with filter option such as default, error, ignore, always, module, once.

The interpreter takes the option as below

error - Turn the warning into an exception.

ignore - Discard the warning.

always - Always emit a warning.

default - Print the warning the first time it is generated from each location.

module - Print the warning the first time it is generated from each module.

once - Print the warning the first time it is generated.

$ python -W default script_with_warning.py # prints first occurrence of a warning message $ python -W error script_with_warning.py # raises exception Issue Warning Message

Warnings are issued by calling the warn() function defined in warnings module. But the issue of a warning message is controlled by warning filter. Rules can be added to the warning filter by calling filterwarnings() and reset to its default state by calling resetwarnings().

The warn method takes an argument message. warning category and stacklevel are optional.

Warning Categories

Warning categories are technically exceptions. With proper warning categories, it gives the ability to group warning messages. Default warning category is “UserWarning”.

List of Warning categories can be found in official docs .

stacklevel=2 makes it to return the caller of the method instead of the source method in warning message.

Warnings Example

Let’s take an example. You provide API that returns the ip address of machine that is making the request. And recently you upgraded your server to support SSL and you want to remove support to insecure API requests.

import urllib2 def get_ip(url): request = urllib2.urlopen(url) response = request.read() return response #calling in some other module def run(): get_user_ip("http://httpbin.org/ip") run() Issue warning message with python warnings module import warnings import urllib2 def get_user_ip(url): if "http://" in url: warnings.warn("Using insecure api endpoint. Please use https url. Support for insecure requests will be removed at the end of 2016.", FutureWarning, stacklevel=2) request = urllib2.urlopen(url) response = request.read() print response return response #calling in some other module def run(): get_user_ip("http://httpbin.org/ip") run() Disable Warning messages with Warning Filters

In addition to issuing warning messages, we can add filters to disable warnings by applying ignore filter to suppress warnings. For example, you can suppress all warning messages by calling

import warnings import urllib2 warnings.simplefilter('ignore') def get_user_ip(url): if "http://" in url: warnings.warn("Deprecation warning. Using insecure api endpoint. Please use https url. Support for insecure requests will be removed at the end of 2016.", FutureWarning, stacklevel=2) request = urllib2.urlopen(url) response = request.read() print response return response #calling in some other module def run(): get_user_ip("http://httpbin.org/ip") run() Links:

Python Warnings