[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-email.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-mailcap.html" />
<link rel="prev" href="module-formatter.html" />
<link rel="parent" href="netdata.html" />
<link rel="next" href="module-email.Message.html" />
<meta name='aesop' content='information' />
<title>12.2 email -- An email and MIME handling package</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.1.4 Writer Implementations"
  href="writer-impls.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. Internet Data Handling"
  href="netdata.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.1 Representing an email"
  href="module-email.Message.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="writer-impls.html">12.1.4 Writer Implementations</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="netdata.html">12. Internet Data Handling</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Message.html">12.2.1 Representing an email</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0014200000000000000000">
12.2 <tt class="module">email</tt> --
	 An email and MIME handling package</A>
</H1>

<P>
<A NAME="module-email"></A>

<P>

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

<P>
The <tt class="module">email</tt> package is a library for managing email messages,
including MIME and other <a class="rfc" id='rfcref-90746' xml:id='rfcref-90746'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-based message documents.  It
subsumes most of the functionality in several older standard modules
such as <tt class="module"><a href="module-rfc822.html">rfc822</a></tt>, <tt class="module"><a href="module-mimetools.html">mimetools</a></tt>,
<tt class="module"><a href="module-multifile.html">multifile</a></tt>, and other non-standard packages such as
<tt class="module">mimecntl</tt>.  It is specifically <em>not</em> designed to do any
sending of email messages to SMTP (<a class="rfc" id='rfcref-90748' xml:id='rfcref-90748'
href="http://www.faqs.org/rfcs/rfc2821.html">RFC 2821</a>) servers; that is the
function of the <tt class="module"><a href="module-smtplib.html">smtplib</a></tt> module.  The <tt class="module">email</tt>
package attempts to be as RFC-compliant as possible, supporting in
addition to <a class="rfc" id='rfcref-90750' xml:id='rfcref-90750'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, such MIME-related RFCs as
<a class="rfc" id='rfcref-90752' xml:id='rfcref-90752'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-90754' xml:id='rfcref-90754'
href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-90756' xml:id='rfcref-90756'
href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-90758' xml:id='rfcref-90758'
href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.

<P>
The primary distinguishing feature of the <tt class="module">email</tt> package is
that it splits the parsing and generating of email messages from the
internal <em>object model</em> representation of email.  Applications
using the <tt class="module">email</tt> package deal primarily with objects; you can
add sub-objects to messages, remove sub-objects from messages,
completely re-arrange the contents, etc.  There is a separate parser
and a separate generator which handles the transformation from flat
text to the object model, and then back to flat text again.  There
are also handy subclasses for some common MIME object types, and a few
miscellaneous utilities that help with such common tasks as extracting
and parsing message field values, creating RFC-compliant dates, etc.

<P>
The following sections describe the functionality of the
<tt class="module">email</tt> package.  The ordering follows a progression that
should be common in applications: an email message is read as flat
text from a file or other source, the text is parsed to produce the
object structure of the email message, this structure is manipulated,
and finally rendered back into flat text.

<P>
It is perfectly feasible to create the object structure out of whole
cloth -- i.e. completely from scratch.  From there, a similar
progression can be taken as above.

<P>
Also included are detailed specifications of all the classes and
modules that the <tt class="module">email</tt> package provides, the exception
classes you might encounter while using the <tt class="module">email</tt> package,
some auxiliary utilities, and a few examples.  For users of the older
<tt class="module">mimelib</tt> package, or previous versions of the <tt class="module">email</tt>
package, a section on differences and porting is provided.

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

    <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-smtplib.html">smtplib</a></tt>:</b>
    <dd>SMTP protocol client.
  </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="module-email.Message.html">12.2.1 Representing an email message</a>
<UL>
<LI><A href="node581.html">12.2.1.1 Deprecated methods</a>
</ul>
<LI><A href="module-email.Parser.html">12.2.2 Parsing email messages</a>
<UL>
<LI><A href="node583.html">12.2.2.1 FeedParser API</a>
<LI><A href="node584.html">12.2.2.2 Parser class API</a>
<LI><A href="node585.html">12.2.2.3 Additional notes</a>
</ul>
<LI><A href="module-email.Generator.html">12.2.3 Generating MIME documents</a>
<UL>
<LI><A href="node587.html">12.2.3.1 Deprecated methods</a>
</ul>
<LI><A href="node588.html">12.2.4 Creating email and MIME objects from scratch</a>
<LI><A href="module-email.Header.html">12.2.5 Internationalized headers</a>
<LI><A href="module-email.Charset.html">12.2.6 Representing character sets</a>
<LI><A href="module-email.Encoders.html">12.2.7 Encoders</a>
<LI><A href="module-email.Errors.html">12.2.8 Exception and Defect classes</a>
<LI><A href="module-email.Utils.html">12.2.9 Miscellaneous utilities</a>
<LI><A href="module-email.Iterators.html">12.2.10 Iterators</a>
<LI><A href="node595.html">12.2.11 Package History</a>
<LI><A href="node596.html">12.2.12 Differences from <tt class="module">mimelib</tt></a>
<LI><A href="node597.html">12.2.13 Examples</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="12.1.4 Writer Implementations"
  href="writer-impls.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. Internet Data Handling"
  href="netdata.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.1 Representing an email"
  href="module-email.Message.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="writer-impls.html">12.1.4 Writer Implementations</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="netdata.html">12. Internet Data Handling</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Message.html">12.2.1 Representing an email</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="module-mailcap.html" />
	13	<link rel="prev" href="module-formatter.html" />
	14	<link rel="parent" href="netdata.html" />
	15	<link rel="next" href="module-email.Message.html" />
	16	<meta name='aesop' content='information' />
	17	<title>12.2 email -- An email and MIME handling package</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.1.4 Writer Implementations"
	25	href="writer-impls.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. Internet Data Handling"
	28	href="netdata.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.1 Representing an email"
	31	href="module-email.Message.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="writer-impls.html">12.1.4 Writer Implementations</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="netdata.html">12. Internet Data Handling</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-email.Message.html">12.2.1 Representing an email</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION0014200000000000000000">
	56	12.2 <tt class="module">email</tt> --
	57	An email and MIME handling package</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-email"></A>
	62
	63	<P>
	64
65	<span class="versionnote">New in version 2.2.</span>
66
67	<P>
68	The <tt class="module">email</tt> package is a library for managing email messages,
69	including MIME and other <a class="rfc" id='rfcref-90746' xml:id='rfcref-90746'
70	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-based message documents. It
71	subsumes most of the functionality in several older standard modules
72	such as <tt class="module"><a href="module-rfc822.html">rfc822</a></tt>, <tt class="module"><a href="module-mimetools.html">mimetools</a></tt>,
73	<tt class="module"><a href="module-multifile.html">multifile</a></tt>, and other non-standard packages such as
74	<tt class="module">mimecntl</tt>. It is specifically <em>not</em> designed to do any
75	sending of email messages to SMTP (<a class="rfc" id='rfcref-90748' xml:id='rfcref-90748'
76	href="http://www.faqs.org/rfcs/rfc2821.html">RFC 2821</a>) servers; that is the
77	function of the <tt class="module"><a href="module-smtplib.html">smtplib</a></tt> module. The <tt class="module">email</tt>
78	package attempts to be as RFC-compliant as possible, supporting in
79	addition to <a class="rfc" id='rfcref-90750' xml:id='rfcref-90750'
80	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>, such MIME-related RFCs as
81	<a class="rfc" id='rfcref-90752' xml:id='rfcref-90752'
82	href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-90754' xml:id='rfcref-90754'
83	href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-90756' xml:id='rfcref-90756'
84	href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-90758' xml:id='rfcref-90758'
85	href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
86
87	<P>
88	The primary distinguishing feature of the <tt class="module">email</tt> package is
89	that it splits the parsing and generating of email messages from the
90	internal <em>object model</em> representation of email. Applications
91	using the <tt class="module">email</tt> package deal primarily with objects; you can
92	add sub-objects to messages, remove sub-objects from messages,
93	completely re-arrange the contents, etc. There is a separate parser
94	and a separate generator which handles the transformation from flat
95	text to the object model, and then back to flat text again. There
96	are also handy subclasses for some common MIME object types, and a few
97	miscellaneous utilities that help with such common tasks as extracting
98	and parsing message field values, creating RFC-compliant dates, etc.
99
100	<P>
101	The following sections describe the functionality of the
102	<tt class="module">email</tt> package. The ordering follows a progression that
103	should be common in applications: an email message is read as flat
104	text from a file or other source, the text is parsed to produce the
105	object structure of the email message, this structure is manipulated,
106	and finally rendered back into flat text.
107
108	<P>
109	It is perfectly feasible to create the object structure out of whole
110	cloth -- i.e. completely from scratch. From there, a similar
111	progression can be taken as above.
112
113	<P>
114	Also included are detailed specifications of all the classes and
115	modules that the <tt class="module">email</tt> package provides, the exception
116	classes you might encounter while using the <tt class="module">email</tt> package,
117	some auxiliary utilities, and a few examples. For users of the older
118	<tt class="module">mimelib</tt> package, or previous versions of the <tt class="module">email</tt>
119	package, a section on differences and porting is provided.
120
121	<P>
122	<div class="seealso">
123	<p class="heading">See Also:</p>
124
125	<dl compact="compact" class="seemodule">
126	<dt>Module <b><tt class="module"><a href="module-smtplib.html">smtplib</a></tt>:</b>
127	<dd>SMTP protocol client.
128	</dl>
129	</div>
130
131	<P>
132
133	<p><br /></p><hr class='online-navigation' />
134	<div class='online-navigation'>
135	<!--Table of Child-Links-->
136	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
137
138	<UL CLASS="ChildLinks">
139	<LI><A href="module-email.Message.html">12.2.1 Representing an email message</a>
140	<UL>
141	<LI><A href="node581.html">12.2.1.1 Deprecated methods</a>
142	</ul>
143	<LI><A href="module-email.Parser.html">12.2.2 Parsing email messages</a>
144	<UL>
145	<LI><A href="node583.html">12.2.2.1 FeedParser API</a>
146	<LI><A href="node584.html">12.2.2.2 Parser class API</a>
147	<LI><A href="node585.html">12.2.2.3 Additional notes</a>
148	</ul>
149	<LI><A href="module-email.Generator.html">12.2.3 Generating MIME documents</a>
150	<UL>
151	<LI><A href="node587.html">12.2.3.1 Deprecated methods</a>
152	</ul>
153	<LI><A href="node588.html">12.2.4 Creating email and MIME objects from scratch</a>
154	<LI><A href="module-email.Header.html">12.2.5 Internationalized headers</a>
155	<LI><A href="module-email.Charset.html">12.2.6 Representing character sets</a>
156	<LI><A href="module-email.Encoders.html">12.2.7 Encoders</a>
157	<LI><A href="module-email.Errors.html">12.2.8 Exception and Defect classes</a>
158	<LI><A href="module-email.Utils.html">12.2.9 Miscellaneous utilities</a>
159	<LI><A href="module-email.Iterators.html">12.2.10 Iterators</a>
160	<LI><A href="node595.html">12.2.11 Package History</a>
161	<LI><A href="node596.html">12.2.12 Differences from <tt class="module">mimelib</tt></a>
162	<LI><A href="node597.html">12.2.13 Examples</a>
163	</ul>
164	<!--End of Table of Child-Links-->
165	</div>
166
167	<DIV CLASS="navigation">
168	<div class='online-navigation'>
169	<p></p><hr />
170	<table align="center" width="100%" cellpadding="0" cellspacing="2">
171	<tr>
172	<td class='online-navigation'><a rel="prev" title="12.1.4 Writer Implementations"
173	href="writer-impls.html"><img src='../icons/previous.png'
174	border='0' height='32' alt='Previous Page' width='32' /></A></td>
175	<td class='online-navigation'><a rel="parent" title="12. Internet Data Handling"
176	href="netdata.html"><img src='../icons/up.png'
177	border='0' height='32' alt='Up One Level' width='32' /></A></td>
178	<td class='online-navigation'><a rel="next" title="12.2.1 Representing an email"
179	href="module-email.Message.html"><img src='../icons/next.png'
180	border='0' height='32' alt='Next Page' width='32' /></A></td>
181	<td align="center" width="100%">Python Library Reference</td>
182	<td class='online-navigation'><a rel="contents" title="Table of Contents"
183	href="contents.html"><img src='../icons/contents.png'
184	border='0' height='32' alt='Contents' width='32' /></A></td>
185	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
186	border='0' height='32' alt='Module Index' width='32' /></a></td>
187	<td class='online-navigation'><a rel="index" title="Index"
188	href="genindex.html"><img src='../icons/index.png'
189	border='0' height='32' alt='Index' width='32' /></A></td>
190	</tr></table>
191	<div class='online-navigation'>
192	<b class="navlabel">Previous:</b>
193	<a class="sectref" rel="prev" href="writer-impls.html">12.1.4 Writer Implementations</A>
194	<b class="navlabel">Up:</b>
195	<a class="sectref" rel="parent" href="netdata.html">12. Internet Data Handling</A>
196	<b class="navlabel">Next:</b>
197	<a class="sectref" rel="next" href="module-email.Message.html">12.2.1 Representing an email</A>
198	</div>
199	</div>
200	<hr />
201	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
202	</DIV>
203	<!--End of Navigation Panel-->
204	<ADDRESS>
205	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
206	</ADDRESS>
207	</BODY>
208	</HTML>