sam-t2/devtools/v8plus/html/python/lib/module-xml.parsers.expat.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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="next" href="module-xml.dom.html" />
<link rel="prev" href="module-htmlentitydefs.html" />
<link rel="parent" href="markup.html" />
<link rel="next" href="xmlparser-objects.html" />
<meta name='aesop' content='information' />
<title>13.5 xml.parsers.expat -- Fast XML parsing using Expat</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.4 htmlentitydefs  "
  href="module-htmlentitydefs.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="13. Structured Markup Processing"
  href="markup.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="13.5.1 XMLParser Objects"
  href="xmlparser-objects.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>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-htmlentitydefs.html">13.4 htmlentitydefs  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="xmlparser-objects.html">13.5.1 XMLParser Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0015500000000000000000">
13.5 <tt class="module">xml.parsers.expat</tt> --
         Fast XML parsing using Expat</A>
</H1>

<P>
<A NAME="module-xml.parsers.expat"></A>

<P>

<span class="versionnote">New in version 2.0.</span>

<P>
The <tt class="module">xml.parsers.expat</tt> module is a Python interface to the
Expat<a id='l2h-4306' xml:id='l2h-4306'></a> non-validating XML parser.
The module provides a single extension type, <tt class="class">xmlparser</tt>, that
represents the current state of an XML parser.  After an
<tt class="class">xmlparser</tt> object has been created, various attributes of the object
can be set to handler functions.  When an XML document is then fed to
the parser, the handler functions are called for the character data
and markup in the XML document.

<P>
This module uses the <tt class="module">pyexpat</tt><a id='l2h-4307' xml:id='l2h-4307'></a> module to
provide access to the Expat parser.  Direct use of the
<tt class="module">pyexpat</tt> module is deprecated.

<P>
This module provides one exception and one type object:

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4301' xml:id='l2h-4301' class="exception">ExpatError</tt></b></dt>
<dd>
  The exception raised when Expat reports an error.  See section
  <A href="expaterror-objects.html#expaterror-objects">13.5.2</A>, ``ExpatError Exceptions,'' for more
  information on interpreting Expat errors.
</dd></dl>

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-4302' xml:id='l2h-4302' class="exception">error</tt></b></dt>
<dd>
  Alias for <tt class="exception">ExpatError</tt>.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-4303' xml:id='l2h-4303'>XMLParserType</tt></b></dt>
<dd>
  The type of the return values from the <tt class="function">ParserCreate()</tt>
  function.
</dd></dl>

<P>
The <tt class="module">xml.parsers.expat</tt> module contains two functions:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4304' xml:id='l2h-4304' class="function">ErrorString</tt></b>(</nobr></td>
  <td><var>errno</var>)</td></tr></table></dt>
<dd>
Returns an explanatory string for a given error number <var>errno</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4305' xml:id='l2h-4305' class="function">ParserCreate</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>encoding</var><big>[</big><var>,
                               namespace_separator</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Creates and returns a new <tt class="class">xmlparser</tt> object.
<var>encoding</var>, if specified, must be a string naming the encoding
used by the XML data.  Expat doesn't support as many encodings as
Python does, and its repertoire of encodings can't be extended; it
supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
<var>encoding</var> is given it will override the implicit or explicit
encoding of the document.

<P>
Expat can optionally do XML namespace processing for you, enabled by
providing a value for <var>namespace_separator</var>.  The value must be a
one-character string; a <tt class="exception">ValueError</tt> will be raised if the
string has an illegal length (<code>None</code> is considered the same as
omission).  When namespace processing is enabled, element type names
and attribute names that belong to a namespace will be expanded.  The
element name passed to the element handlers
<tt class="member">StartElementHandler</tt> and <tt class="member">EndElementHandler</tt>
will be the concatenation of the namespace URI, the namespace
separator character, and the local part of the name.  If the namespace
separator is a zero byte (<code>chr(0)</code>) then the namespace URI and
the local part will be concatenated without any separator.

<P>
For example, if <var>namespace_separator</var> is set to a space character
("<tt class="character"> </tt>") and the following document is parsed:

<P>
<div class="verbatim"><pre>
&lt;?xml version="1.0"?&gt;
&lt;root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/"&gt;
  &lt;py:elem1 /&gt;
  &lt;elem2 xmlns="" /&gt;
&lt;/root&gt;
</pre></div>

<P>
<tt class="member">StartElementHandler</tt> will receive the following strings
for each element:

<P>
<div class="verbatim"><pre>
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
</pre></div>
</dl>

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seetitle">
    <dt><em class="citetitle"><a href="http://www.libexpat.org/"
        >The Expat XML Parser</a></em></dt>
    <dd>Home page of the Expat project.</dd>
  </dl>
</div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="xmlparser-objects.html">13.5.1 XMLParser Objects</a>
<LI><A href="expaterror-objects.html">13.5.2 ExpatError Exceptions</a>
<LI><A href="expat-example.html">13.5.3 Example</a>
<LI><A href="expat-content-models.html">13.5.4 Content Model Descriptions</a>
<LI><A href="expat-errors.html">13.5.5 Expat error constants</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="13.4 htmlentitydefs  "
  href="module-htmlentitydefs.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="13. Structured Markup Processing"
  href="markup.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="13.5.1 XMLParser Objects"
  href="xmlparser-objects.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>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-htmlentitydefs.html">13.4 htmlentitydefs  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="markup.html">13. Structured Markup Processing</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="xmlparser-objects.html">13.5.1 XMLParser Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>