Python in a Nutshell

Name

warn

Synopsis

warn(message,category=UserWarning,stacklevel=1)

Sends a warning, so that the filters examine and possibly output it. The location of the warning is the current function (caller of warn) if stacklevel is 1, or its caller if stacklevel is 2. Thus, passing 2 as the value of stacklevel lets you write functions that send warnings on their caller’s behalf, such as:

def toUnicode(astr):
    try: 
        return unicode(astr)
    except UnicodeError:
        warnings.warn("Invalid characters in (%s)"%astr, 
                      stacklevel=2)
        return unicode(astr, errors='ignore')

Thanks to parameter stacklevel =2, the warning appears as coming from the caller of toUnicode, rather than from function toUnicode itself. This is particularly important when the action of the filter matching this warning is default or module, since these actions output a warning only the first time the warning occurs from a given location or module.