[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="node584.html" />
	13	<link rel="prev" href="module-email.Parser.html" />
	14	<link rel="parent" href="module-email.Parser.html" />
	15	<link rel="next" href="node584.html" />
	16	<meta name='aesop' content='information' />
	17	<title>12.2.2.1 FeedParser API</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="12.2.2 Parsing email messages"
	25	href="module-email.Parser.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="12.2.2 Parsing email messages"
	28	href="module-email.Parser.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="12.2.2.2 Parser class API"
	31	href="node584.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="node584.html">12.2.2.2 Parser class API</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H3><A NAME="SECTION0014221000000000000000">
	56	12.2.2.1 FeedParser API</A>
	57	</H3>
	58
	59	<P>
	60
	61	<span class="versionnote">New in version 2.4.</span>
	62
	63	<P>
	64	The <tt class="class">FeedParser</tt> provides an API that is conducive to incremental
65	parsing of email messages, such as would be necessary when reading the text of
66	an email message from a source that can block (e.g. a socket). The
67	<tt class="class">FeedParser</tt> can of course be used to parse an email message fully
68	contained in a string or a file, but the classic <tt class="class">Parser</tt> API may be
69	more convenient for such use cases. The semantics and results of the two
70	parser APIs are identical.
71
72	<P>
73	The <tt class="class">FeedParser</tt>'s API is simple; you create an instance, feed it a
74	bunch of text until there's no more to feed it, then close the parser to
75	retrieve the root message object. The <tt class="class">FeedParser</tt> is extremely
76	accurate when parsing standards-compliant messages, and it does a very good
77	job of parsing non-compliant messages, providing information about how a
78	message was deemed broken. It will populate a message object's <var>defects</var>
79	attribute with a list of any problems it found in a message. See the
80	<tt class="module"><a href="module-email.Errors.html">email.Errors</a></tt> module for the list of defects that it can find.
81
82	<P>
83	Here is the API for the <tt class="class">FeedParser</tt>:
84
85	<P>
86	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
87	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3876' xml:id='l2h-3876' class="class">FeedParser</tt></b>(</nobr></td>
88	<td><var></var><big>[</big><var>_factory</var><big>]</big><var></var>)</td></tr></table></dt>
89	<dd>
90	Create a <tt class="class">FeedParser</tt> instance. Optional <var>_factory</var> is a
91	no-argument callable that will be called whenever a new message object is
92	needed. It defaults to the <tt class="class">email.Message.Message</tt> class.
93	</dl>
94
95	<P>
96	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
97	<td><nobr><b><tt id='l2h-3877' xml:id='l2h-3877' class="method">feed</tt></b>(</nobr></td>
98	<td><var>data</var>)</td></tr></table></dt>
99	<dd>
100	Feed the <tt class="class">FeedParser</tt> some more data. <var>data</var> should be a
101	string containing one or more lines. The lines can be partial and the
102	<tt class="class">FeedParser</tt> will stitch such partial lines together properly. The
103	lines in the string can have any of the common three line endings, carriage
104	return, newline, or carriage return and newline (they can even be mixed).
105	</dl>
106
107	<P>
108	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
109	<td><nobr><b><tt id='l2h-3878' xml:id='l2h-3878' class="method">close</tt></b>(</nobr></td>
110	<td><var></var>)</td></tr></table></dt>
111	<dd>
112	Closing a <tt class="class">FeedParser</tt> completes the parsing of all previously fed data,
113	and returns the root message object. It is undefined what happens if you feed
114	more data to a closed <tt class="class">FeedParser</tt>.
115	</dl>
116
117	<P>
118
119	<DIV CLASS="navigation">
120	<div class='online-navigation'>
121	<p></p><hr />
122	<table align="center" width="100%" cellpadding="0" cellspacing="2">
123	<tr>
124	<td class='online-navigation'><a rel="prev" title="12.2.2 Parsing email messages"
125	href="module-email.Parser.html"><img src='../icons/previous.png'
126	border='0' height='32' alt='Previous Page' width='32' /></A></td>
127	<td class='online-navigation'><a rel="parent" title="12.2.2 Parsing email messages"
128	href="module-email.Parser.html"><img src='../icons/up.png'
129	border='0' height='32' alt='Up One Level' width='32' /></A></td>
130	<td class='online-navigation'><a rel="next" title="12.2.2.2 Parser class API"
131	href="node584.html"><img src='../icons/next.png'
132	border='0' height='32' alt='Next Page' width='32' /></A></td>
133	<td align="center" width="100%">Python Library Reference</td>
134	<td class='online-navigation'><a rel="contents" title="Table of Contents"
135	href="contents.html"><img src='../icons/contents.png'
136	border='0' height='32' alt='Contents' width='32' /></A></td>
137	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
138	border='0' height='32' alt='Module Index' width='32' /></a></td>
139	<td class='online-navigation'><a rel="index" title="Index"
140	href="genindex.html"><img src='../icons/index.png'
141	border='0' height='32' alt='Index' width='32' /></A></td>
142	</tr></table>
143	<div class='online-navigation'>
144	<b class="navlabel">Previous:</b>
145	<a class="sectref" rel="prev" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
146	<b class="navlabel">Up:</b>
147	<a class="sectref" rel="parent" href="module-email.Parser.html">12.2.2 Parsing email messages</A>
148	<b class="navlabel">Next:</b>
149	<a class="sectref" rel="next" href="node584.html">12.2.2.2 Parser class API</A>
150	</div>
151	</div>
152	<hr />
153	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
154	</DIV>
155	<!--End of Navigation Panel-->
156	<ADDRESS>
157	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
158	</ADDRESS>
159	</BODY>
160	</HTML>