26.4.3 Available Functions

Python 2.5

previous page next page

26.4.3 Available Functions

warn( message[, category[, stacklevel]])

Issue a warning, or maybe ignore it or raise an exception. The category argument, if given, must be a warning category class (see above); it defaults to UserWarning. Alternatively message can be a Warning instance, in which case category will be ignored and message.__class__ will be used. In this case the message text will be str(message). This function raises an exception if the particular warning issued is changed into an error by the warnings filter see above. The stacklevel argument can be used by wrapper functions written in Python, like this:

def deprecation(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)

This makes the warning refer to deprecation()'s caller, rather than to the source of deprecation() itself (since the latter would defeat the purpose of the warning message).

warn_explicit( message, category, filename, lineno[, module[, registry[, module_globals]]]): This is a low-level interface to the functionality of warn(), passing in explicitly the message, category, filename and line number, and optionally the module name and the registry (which should be the __warningregistry__ 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 Warning or message may be a 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 source for modules found in zipfiles or other non-filesystem import sources, and was added in Python 2.5.)

showwarning( message, category, filename, lineno[, file]): Write a warning to a file. The default implementation calls formatwarning(message, category, filename, lineno) and writes the resulting string to file, which defaults to sys.stderr. You may replace this function with an alternative implementation by assigning to warnings.showwarning.

formatwarning( message, category, filename, lineno): Format a warning the standard way. This returns a string which may contain embedded newlines and ends in a newline.

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 the front of the list override entries later in the list, if both match a particular warning. Omitted arguments default to a value that matches everything.

simplefilter( action[, category[, lineno[, append]]]): Insert a simple entry into the list of warnings filters. The meaning of the function parameters is as for filterwarnings(), but regular expressions are not needed as the filter inserted always matches any message in any module as long as the category and line number match.

resetwarnings( ): Reset the warnings filter. This discards the effect of all previous calls to filterwarnings(), including that of the -W command line options and calls to simplefilter().

See About this document... for information on suggesting changes.

previous page start next page