<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"warning-filter.html" />
<link rel=
"parent" href=
"module-warnings.html" />
<link rel=
"next" href=
"module-imp.html" />
<meta name='aesop' content='information'
/>
<title>3.20.3 Available Functions
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3.20.2 The Warnings Filter"
href=
"warning-filter.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"3.20 warnings "
href=
"module-warnings.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"3.21 imp "
href=
"module-imp.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"warning-filter.html">3.20.2 The Warnings Filter
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-warnings.html">3.20 warnings
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-imp.html">3.21 imp
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION0052030000000000000000"></A><A NAME=
"warning-functions"></A>
3.20.3 Available Functions
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
689' xml:id='l2h-
689'
class=
"function">warn
</tt></b>(
</nobr></td>
<td><var>message
</var><big>[
</big><var>, category
</var><big>[
</big><var>, stacklevel
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Issue a warning, or maybe ignore it or raise an exception. The
<var>category
</var> argument, if given, must be a warning category class
(see above); it defaults to
<tt class=
"exception">UserWarning
</tt>. Alternatively
<var>message
</var> can be a
<tt class=
"exception">Warning
</tt> instance, in which case
<var>category
</var> will be ignored and
<code>message.__class__
</code> will be used.
In this case the message text will be
<code>str(message)
</code>. This function
raises an exception if the particular warning issued is changed
into an error by the warnings filter see above. The
<var>stacklevel
</var>
argument can be used by wrapper functions written in Python, like
<div class=
"verbatim"><pre>
def deprecation(message):
warnings.warn(message, DeprecationWarning, stacklevel=
2)
This makes the warning refer to
<tt class=
"function">deprecation()
</tt>'s caller,
rather than to the source of
<tt class=
"function">deprecation()
</tt> itself (since
the latter would defeat the purpose of the warning message).
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
690' xml:id='l2h-
690'
class=
"function">warn_explicit
</tt></b>(
</nobr></td>
<td><var>message, category, filename,
lineno
</var><big>[
</big><var>, module
</var><big>[
</big><var>, registry
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
This is a low-level interface to the functionality of
<tt class=
"function">warn()
</tt>, passing in explicitly the message, category,
filename and line number, and optionally the module name and the
registry (which should be the
<code>__warningregistry__
</code> dictionary of
the module). The module name defaults to the filename with
<code>.py
</code>
stripped; if no registry is passed, the warning is never suppressed.
<var>message
</var> must be a string and
<var>category
</var> a subclass of
<tt class=
"exception">Warning
</tt> or
<var>message
</var> may be a
<tt class=
"exception">Warning
</tt> instance,
in which case
<var>category
</var> will be ignored.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
691' xml:id='l2h-
691'
class=
"function">showwarning
</tt></b>(
</nobr></td>
<td><var>message, category, filename,
lineno
</var><big>[
</big><var>, file
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Write a warning to a file. The default implementation calls
<code>formatwarning(
<var>message
</var>,
<var>category
</var>,
<var>filename
</var>,
<var>lineno
</var>)
</code> and writes the resulting string to
<var>file
</var>, which
defaults to
<code>sys.stderr
</code>. You may replace this function with an
alternative implementation by assigning to
<code>warnings.showwarning
</code>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
692' xml:id='l2h-
692'
class=
"function">formatwarning
</tt></b>(
</nobr></td>
<td><var>message, category, filename, lineno
</var>)
</td></tr></table></dt>
Format a warning the standard way. This returns a string which may
contain embedded newlines and ends in a newline.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
693' xml:id='l2h-
693'
class=
"function">filterwarnings
</tt></b>(
</nobr></td>
<td><var>action
</var><big>[
</big><var>,
message
</var><big>[
</big><var>, category
</var><big>[
</big><var>,
module
</var><big>[
</big><var>, lineno
</var><big>[
</big><var>, append
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
Insert an entry into the list of warnings filters. The entry is
inserted at the front by default; if
<var>append
</var> is true, it is
This checks the types of the arguments, compiles the message and
module regular expressions, and inserts them as a tuple in front
of the warnings filter. Entries inserted later override entries
inserted earlier, if both match a particular warning. Omitted
arguments default to a value that matches everything.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
694' xml:id='l2h-
694'
class=
"function">resetwarnings
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
Reset the warnings filter. This discards the effect of all previous
calls to
<tt class=
"function">filterwarnings()
</tt>, including that of the
<b class=
"programopt">-W
</b> command line options.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3.20.2 The Warnings Filter"
href=
"warning-filter.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"3.20 warnings "
href=
"module-warnings.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"3.21 imp "
href=
"module-imp.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"warning-filter.html">3.20.2 The Warnings Filter
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-warnings.html">3.20 warnings
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-imp.html">3.21 imp
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.