sam-t2/devtools/amd64/html/python/lib/node583.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="node584.html" />
<link rel="prev" href="module-email.Parser.html" />
<link rel="parent" href="module-email.Parser.html" />
<link rel="next" href="node584.html" />
<meta name='aesop' content='information' />
<title>12.2.2.1 FeedParser API</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="12.2.2 Parsing email messages"
  href="module-email.Parser.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="12.2.2 Parsing email messages"
  href="module-email.Parser.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="12.2.2.2 Parser class API"
  href="node584.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-email.Parser.html">12.2.2 Parsing email messages</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node584.html">12.2.2.2 Parser class API</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H3><A NAME="SECTION0014221000000000000000">
12.2.2.1 FeedParser API</A>
</H3>

<P>

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

<P>
The <tt class="class">FeedParser</tt> provides an API that is conducive to incremental
parsing of email messages, such as would be necessary when reading the text of
an email message from a source that can block (e.g. a socket).  The
<tt class="class">FeedParser</tt> can of course be used to parse an email message fully
contained in a string or a file, but the classic <tt class="class">Parser</tt> API may be
more convenient for such use cases.  The semantics and results of the two
parser APIs are identical.

<P>
The <tt class="class">FeedParser</tt>'s API is simple; you create an instance, feed it a
bunch of text until there's no more to feed it, then close the parser to
retrieve the root message object.  The <tt class="class">FeedParser</tt> is extremely
accurate when parsing standards-compliant messages, and it does a very good
job of parsing non-compliant messages, providing information about how a
message was deemed broken.  It will populate a message object's <var>defects</var>
attribute with a list of any problems it found in a message.  See the
<tt class="module"><a href="module-email.Errors.html">email.Errors</a></tt> module for the list of defects that it can find.

<P>
Here is the API for the <tt class="class">FeedParser</tt>:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3876' xml:id='l2h-3876' class="class">FeedParser</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>_factory</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Create a <tt class="class">FeedParser</tt> instance.  Optional <var>_factory</var> is a
no-argument callable that will be called whenever a new message object is
needed.  It defaults to the <tt class="class">email.Message.Message</tt> class.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3877' xml:id='l2h-3877' class="method">feed</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Feed the <tt class="class">FeedParser</tt> some more data.  <var>data</var> should be a
string containing one or more lines.  The lines can be partial and the
<tt class="class">FeedParser</tt> will stitch such partial lines together properly.  The
lines in the string can have any of the common three line endings, carriage
return, newline, or carriage return and newline (they can even be mixed).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3878' xml:id='l2h-3878' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Closing a <tt class="class">FeedParser</tt> completes the parsing of all previously fed data,
and returns the root message object.  It is undefined what happens if you feed
more data to a closed <tt class="class">FeedParser</tt>.
</dl>

<P>

<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="12.2.2 Parsing email messages"
  href="module-email.Parser.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="12.2.2 Parsing email messages"
  href="module-email.Parser.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="12.2.2.2 Parser class API"
  href="node584.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-email.Parser.html">12.2.2 Parsing email messages</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node584.html">12.2.2.2 Parser class API</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>