[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / lib / module-email.Header.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-email.Charset.html" />
<link rel="prev" href="node588.html" />
<link rel="parent" href="module-email.html" />
<link rel="next" href="module-email.Charset.html" />
<meta name='aesop' content='information' />
<title>12.2.5 Internationalized headers</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.4 Creating email and"
  href="node588.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 email  "
  href="module-email.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.6 Representing character sets"
  href="module-email.Charset.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="node588.html">12.2.4 Creating email and</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Charset.html">12.2.6 Representing character sets</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0014250000000000000000">
12.2.5 Internationalized headers</A>
</H2>
<A NAME="module-email.Header"></A>

<P>
<a class="rfc" id='rfcref-90877' xml:id='rfcref-90877'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is the base standard that describes the format of email
messages.  It derives from the older <a class="rfc" id='rfcref-90879' xml:id='rfcref-90879'
href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> standard which came
into widespread use at a time when most email was composed of ASCII
characters only.  <a class="rfc" id='rfcref-90881' xml:id='rfcref-90881'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is a specification written assuming email
contains only 7-bit ASCII characters.

<P>
Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now
be used in email messages.  The base standard still requires email
messages to be transferred using only 7-bit ASCII characters, so a
slew of RFCs have been written describing how to encode email
containing non-ASCII characters into <a class="rfc" id='rfcref-90883' xml:id='rfcref-90883'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant format.
These RFCs include <a class="rfc" id='rfcref-90885' xml:id='rfcref-90885'
href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-90887' xml:id='rfcref-90887'
href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-90889' xml:id='rfcref-90889'
href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-90891' xml:id='rfcref-90891'
href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
The <tt class="module">email</tt> package supports these standards in its
<tt class="module">email.Header</tt> and <tt class="module">email.Charset</tt> modules.

<P>
If you want to include non-ASCII characters in your email headers,
say in the <span class="mailheader">Subject:</span> or <span class="mailheader">To:</span> fields, you should
use the <tt class="class">Header</tt> class and assign the field in the
<tt class="class">Message</tt> object to an instance of <tt class="class">Header</tt> instead of
using a string for the header value.  For example:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; from email.Message import Message
&gt;&gt;&gt; from email.Header import Header
&gt;&gt;&gt; msg = Message()
&gt;&gt;&gt; h = Header('p\xf6stal', 'iso-8859-1')
&gt;&gt;&gt; msg['Subject'] = h
&gt;&gt;&gt; print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=
</pre></div>

<P>
Notice here how we wanted the <span class="mailheader">Subject:</span> field to contain a
non-ASCII character?  We did this by creating a <tt class="class">Header</tt>
instance and passing in the character set that the byte string was
encoded in.  When the subsequent <tt class="class">Message</tt> instance was
flattened, the <span class="mailheader">Subject:</span> field was properly <a class="rfc" id='rfcref-90893' xml:id='rfcref-90893'
href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
encoded.  MIME-aware mail readers would show this header using the
embedded ISO-8859-1 character.

<P>

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

<P>
Here is the <tt class="class">Header</tt> class description:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3899' xml:id='l2h-3899' class="class">Header</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>s</var><big>[</big><var>, charset</var><big>[</big><var>,
    maxlinelen</var><big>[</big><var>, header_name</var><big>[</big><var>, continuation_ws</var><big>[</big><var>,
    errors</var><big>]</big><var></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>
<dd>
Create a MIME-compliant header that can contain strings in different
character sets.

<P>
Optional <var>s</var> is the initial header value.  If <code>None</code> (the
default), the initial header value is not set.  You can later append
to the header with <tt class="method">append()</tt> method calls.  <var>s</var> may be a
byte string or a Unicode string, but see the <tt class="method">append()</tt>
documentation for semantics.

<P>
Optional <var>charset</var> serves two purposes: it has the same meaning as
the <var>charset</var> argument to the <tt class="method">append()</tt> method.  It also
sets the default character set for all subsequent <tt class="method">append()</tt>
calls that omit the <var>charset</var> argument.  If <var>charset</var> is not
provided in the constructor (the default), the <code>us-ascii</code>
character set is used both as <var>s</var>'s initial charset and as the
default for subsequent <tt class="method">append()</tt> calls.

<P>
The maximum line length can be specified explicit via
<var>maxlinelen</var>.  For splitting the first line to a shorter value (to
account for the field header which isn't included in <var>s</var>,
e.g. <span class="mailheader">Subject:</span>) pass in the name of the field in
<var>header_name</var>.  The default <var>maxlinelen</var> is 76, and the
default value for <var>header_name</var> is <code>None</code>, meaning it is not
taken into account for the first line of a long, split header.

<P>
Optional <var>continuation_ws</var> must be <a class="rfc" id='rfcref-90895' xml:id='rfcref-90895'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant folding
whitespace, and is usually either a space or a hard tab character.
This character will be prepended to continuation lines.
</dl>

<P>
Optional <var>errors</var> is passed straight through to the
<tt class="method">append()</tt> method.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3900' xml:id='l2h-3900' class="method">append</tt></b>(</nobr></td>
  <td><var>s</var><big>[</big><var>, charset</var><big>[</big><var>, errors</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Append the string <var>s</var> to the MIME header.

<P>
Optional <var>charset</var>, if given, should be a <tt class="class">Charset</tt> instance
(see <tt class="module"><a href="module-email.Charset.html">email.Charset</a></tt>) or the name of a character set, which
will be converted to a <tt class="class">Charset</tt> instance.  A value of
<code>None</code> (the default) means that the <var>charset</var> given in the
constructor is used.

<P>
<var>s</var> may be a byte string or a Unicode string.  If it is a byte
string (i.e. <code>isinstance(s, str)</code> is true), then
<var>charset</var> is the encoding of that byte string, and a
<tt class="exception">UnicodeError</tt> will be raised if the string cannot be
decoded with that character set.

<P>
If <var>s</var> is a Unicode string, then <var>charset</var> is a hint
specifying the character set of the characters in the string.  In this
case, when producing an <a class="rfc" id='rfcref-90897' xml:id='rfcref-90897'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant header using <a class="rfc" id='rfcref-90899' xml:id='rfcref-90899'
href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
rules, the Unicode string will be encoded using the following charsets
in order: <code>us-ascii</code>, the <var>charset</var> hint, <code>utf-8</code>.  The
first character set to not provoke a <tt class="exception">UnicodeError</tt> is used.

<P>
Optional <var>errors</var> is passed through to any <tt class="function">unicode()</tt> or
<tt class="function">ustr.encode()</tt> call, and defaults to ``strict''.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3901' xml:id='l2h-3901' class="method">encode</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>splitchars</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Encode a message header into an RFC-compliant format, possibly
wrapping long lines and encapsulating non-ASCII parts in base64 or
quoted-printable encodings.  Optional <var>splitchars</var> is a string
containing characters to split long ASCII lines on, in rough support
of <a class="rfc" id='rfcref-90901' xml:id='rfcref-90901'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>'s <em>highest level syntactic breaks</em>.  This doesn't
affect <a class="rfc" id='rfcref-90903' xml:id='rfcref-90903'
href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a> encoded lines.
</dl>

<P>
The <tt class="class">Header</tt> class also provides a number of methods to support
standard operators and built-in functions.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3902' xml:id='l2h-3902' class="method">__str__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
A synonym for <tt class="method">Header.encode()</tt>.  Useful for
<code>str(aHeader)</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3903' xml:id='l2h-3903' class="method">__unicode__</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
A helper for the built-in <tt class="function">unicode()</tt> function.  Returns the
header as a Unicode string.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3904' xml:id='l2h-3904' class="method">__eq__</tt></b>(</nobr></td>
  <td><var>other</var>)</td></tr></table></dt>
<dd>
This method allows you to compare two <tt class="class">Header</tt> instances for equality.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3905' xml:id='l2h-3905' class="method">__ne__</tt></b>(</nobr></td>
  <td><var>other</var>)</td></tr></table></dt>
<dd>
This method allows you to compare two <tt class="class">Header</tt> instances for inequality.
</dl>

<P>
The <tt class="module">email.Header</tt> module also provides the following
convenient functions.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3906' xml:id='l2h-3906' class="function">decode_header</tt></b>(</nobr></td>
  <td><var>header</var>)</td></tr></table></dt>
<dd>
Decode a message header value without converting the character set.
The header value is in <var>header</var>.

<P>
This function returns a list of <code>(decoded_string, charset)</code> pairs
containing each of the decoded parts of the header.  <var>charset</var> is
<code>None</code> for non-encoded parts of the header, otherwise a lower
case string containing the name of the character set specified in the
encoded string.

<P>
Here's an example:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; from email.Header import decode_header
&gt;&gt;&gt; decode_header('=?iso-8859-1?q?p=F6stal?=')
[('p\xf6stal', 'iso-8859-1')]
</pre></div>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3907' xml:id='l2h-3907' class="function">make_header</tt></b>(</nobr></td>
  <td><var>decoded_seq</var><big>[</big><var>, maxlinelen</var><big>[</big><var>,
    header_name</var><big>[</big><var>, continuation_ws</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Create a <tt class="class">Header</tt> instance from a sequence of pairs as returned
by <tt class="function">decode_header()</tt>.

<P>
<tt class="function">decode_header()</tt> takes a header value string and returns a
sequence of pairs of the format <code>(decoded_string, charset)</code> where
<var>charset</var> is the name of the character set.

<P>
This function takes one of those sequence of pairs and returns a
<tt class="class">Header</tt> instance.  Optional <var>maxlinelen</var>,
<var>header_name</var>, and <var>continuation_ws</var> are as in the
<tt class="class">Header</tt> constructor.
</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.4 Creating email and"
  href="node588.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 email  "
  href="module-email.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.6 Representing character sets"
  href="module-email.Charset.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="node588.html">12.2.4 Creating email and</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Charset.html">12.2.6 Representing character sets</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-email.Charset.html" />
	13	<link rel="prev" href="node588.html" />
	14	<link rel="parent" href="module-email.html" />
	15	<link rel="next" href="module-email.Charset.html" />
	16	<meta name='aesop' content='information' />
	17	<title>12.2.5 Internationalized headers</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.4 Creating email and"
	25	href="node588.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 email "
	28	href="module-email.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.6 Representing character sets"
	31	href="module-email.Charset.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="node588.html">12.2.4 Creating email and</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-email.html">12.2 email </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-email.Charset.html">12.2.6 Representing character sets</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION0014250000000000000000">
	56	12.2.5 Internationalized headers</A>
	57	</H2>
	58	<A NAME="module-email.Header"></A>
	59
	60	<P>
	61	<a class="rfc" id='rfcref-90877' xml:id='rfcref-90877'
	62	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is the base standard that describes the format of email
	63	messages. It derives from the older <a class="rfc" id='rfcref-90879' xml:id='rfcref-90879'
	64	href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a> standard which came
65	into widespread use at a time when most email was composed of ASCII
66	characters only. <a class="rfc" id='rfcref-90881' xml:id='rfcref-90881'
67	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> is a specification written assuming email
68	contains only 7-bit ASCII characters.
69
70	<P>
71	Of course, as email has been deployed worldwide, it has become
72	internationalized, such that language specific character sets can now
73	be used in email messages. The base standard still requires email
74	messages to be transferred using only 7-bit ASCII characters, so a
75	slew of RFCs have been written describing how to encode email
76	containing non-ASCII characters into <a class="rfc" id='rfcref-90883' xml:id='rfcref-90883'
77	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant format.
78	These RFCs include <a class="rfc" id='rfcref-90885' xml:id='rfcref-90885'
79	href="http://www.faqs.org/rfcs/rfc2045.html">RFC 2045</a>, <a class="rfc" id='rfcref-90887' xml:id='rfcref-90887'
80	href="http://www.faqs.org/rfcs/rfc2046.html">RFC 2046</a>, <a class="rfc" id='rfcref-90889' xml:id='rfcref-90889'
81	href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>, and <a class="rfc" id='rfcref-90891' xml:id='rfcref-90891'
82	href="http://www.faqs.org/rfcs/rfc2231.html">RFC 2231</a>.
83	The <tt class="module">email</tt> package supports these standards in its
84	<tt class="module">email.Header</tt> and <tt class="module">email.Charset</tt> modules.
85
86	<P>
87	If you want to include non-ASCII characters in your email headers,
88	say in the <span class="mailheader">Subject:</span> or <span class="mailheader">To:</span> fields, you should
89	use the <tt class="class">Header</tt> class and assign the field in the
90	<tt class="class">Message</tt> object to an instance of <tt class="class">Header</tt> instead of
91	using a string for the header value. For example:
92
93	<P>
94	<div class="verbatim"><pre>
95	>>> from email.Message import Message
96	>>> from email.Header import Header
97	>>> msg = Message()
98	>>> h = Header('p\xf6stal', 'iso-8859-1')
99	>>> msg['Subject'] = h
100	>>> print msg.as_string()
101	Subject: =?iso-8859-1?q?p=F6stal?=
102	</pre></div>
103
104	<P>
105	Notice here how we wanted the <span class="mailheader">Subject:</span> field to contain a
106	non-ASCII character? We did this by creating a <tt class="class">Header</tt>
107	instance and passing in the character set that the byte string was
108	encoded in. When the subsequent <tt class="class">Message</tt> instance was
109	flattened, the <span class="mailheader">Subject:</span> field was properly <a class="rfc" id='rfcref-90893' xml:id='rfcref-90893'
110	href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
111	encoded. MIME-aware mail readers would show this header using the
112	embedded ISO-8859-1 character.
113
114	<P>
115
116	<span class="versionnote">New in version 2.2.2.</span>
117
118	<P>
119	Here is the <tt class="class">Header</tt> class description:
120
121	<P>
122	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
123	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3899' xml:id='l2h-3899' class="class">Header</tt></b>(</nobr></td>
124	<td><var></var><big>[</big><var>s</var><big>[</big><var>, charset</var><big>[</big><var>,
125	maxlinelen</var><big>[</big><var>, header_name</var><big>[</big><var>, continuation_ws</var><big>[</big><var>,
126	errors</var><big>]</big><var></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>
127	<dd>
128	Create a MIME-compliant header that can contain strings in different
129	character sets.
130
131	<P>
132	Optional <var>s</var> is the initial header value. If <code>None</code> (the
133	default), the initial header value is not set. You can later append
134	to the header with <tt class="method">append()</tt> method calls. <var>s</var> may be a
135	byte string or a Unicode string, but see the <tt class="method">append()</tt>
136	documentation for semantics.
137
138	<P>
139	Optional <var>charset</var> serves two purposes: it has the same meaning as
140	the <var>charset</var> argument to the <tt class="method">append()</tt> method. It also
141	sets the default character set for all subsequent <tt class="method">append()</tt>
142	calls that omit the <var>charset</var> argument. If <var>charset</var> is not
143	provided in the constructor (the default), the <code>us-ascii</code>
144	character set is used both as <var>s</var>'s initial charset and as the
145	default for subsequent <tt class="method">append()</tt> calls.
146
147	<P>
148	The maximum line length can be specified explicit via
149	<var>maxlinelen</var>. For splitting the first line to a shorter value (to
150	account for the field header which isn't included in <var>s</var>,
151	e.g. <span class="mailheader">Subject:</span>) pass in the name of the field in
152	<var>header_name</var>. The default <var>maxlinelen</var> is 76, and the
153	default value for <var>header_name</var> is <code>None</code>, meaning it is not
154	taken into account for the first line of a long, split header.
155
156	<P>
157	Optional <var>continuation_ws</var> must be <a class="rfc" id='rfcref-90895' xml:id='rfcref-90895'
158	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant folding
159	whitespace, and is usually either a space or a hard tab character.
160	This character will be prepended to continuation lines.
161	</dl>
162
163	<P>
164	Optional <var>errors</var> is passed straight through to the
165	<tt class="method">append()</tt> method.
166
167	<P>
168	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
169	<td><nobr><b><tt id='l2h-3900' xml:id='l2h-3900' class="method">append</tt></b>(</nobr></td>
170	<td><var>s</var><big>[</big><var>, charset</var><big>[</big><var>, errors</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
171	<dd>
172	Append the string <var>s</var> to the MIME header.
173
174	<P>
175	Optional <var>charset</var>, if given, should be a <tt class="class">Charset</tt> instance
176	(see <tt class="module"><a href="module-email.Charset.html">email.Charset</a></tt>) or the name of a character set, which
177	will be converted to a <tt class="class">Charset</tt> instance. A value of
178	<code>None</code> (the default) means that the <var>charset</var> given in the
179	constructor is used.
180
181	<P>
182	<var>s</var> may be a byte string or a Unicode string. If it is a byte
183	string (i.e. <code>isinstance(s, str)</code> is true), then
184	<var>charset</var> is the encoding of that byte string, and a
185	<tt class="exception">UnicodeError</tt> will be raised if the string cannot be
186	decoded with that character set.
187
188	<P>
189	If <var>s</var> is a Unicode string, then <var>charset</var> is a hint
190	specifying the character set of the characters in the string. In this
191	case, when producing an <a class="rfc" id='rfcref-90897' xml:id='rfcref-90897'
192	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-compliant header using <a class="rfc" id='rfcref-90899' xml:id='rfcref-90899'
193	href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a>
194	rules, the Unicode string will be encoded using the following charsets
195	in order: <code>us-ascii</code>, the <var>charset</var> hint, <code>utf-8</code>. The
196	first character set to not provoke a <tt class="exception">UnicodeError</tt> is used.
197
198	<P>
199	Optional <var>errors</var> is passed through to any <tt class="function">unicode()</tt> or
200	<tt class="function">ustr.encode()</tt> call, and defaults to ``strict''.
201	</dl>
202
203	<P>
204	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
205	<td><nobr><b><tt id='l2h-3901' xml:id='l2h-3901' class="method">encode</tt></b>(</nobr></td>
206	<td><var></var><big>[</big><var>splitchars</var><big>]</big><var></var>)</td></tr></table></dt>
207	<dd>
208	Encode a message header into an RFC-compliant format, possibly
209	wrapping long lines and encapsulating non-ASCII parts in base64 or
210	quoted-printable encodings. Optional <var>splitchars</var> is a string
211	containing characters to split long ASCII lines on, in rough support
212	of <a class="rfc" id='rfcref-90901' xml:id='rfcref-90901'
213	href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>'s <em>highest level syntactic breaks</em>. This doesn't
214	affect <a class="rfc" id='rfcref-90903' xml:id='rfcref-90903'
215	href="http://www.faqs.org/rfcs/rfc2047.html">RFC 2047</a> encoded lines.
216	</dl>
217
218	<P>
219	The <tt class="class">Header</tt> class also provides a number of methods to support
220	standard operators and built-in functions.
221
222	<P>
223	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
224	<td><nobr><b><tt id='l2h-3902' xml:id='l2h-3902' class="method">__str__</tt></b>(</nobr></td>
225	<td><var></var>)</td></tr></table></dt>
226	<dd>
227	A synonym for <tt class="method">Header.encode()</tt>. Useful for
228	<code>str(aHeader)</code>.
229	</dl>
230
231	<P>
232	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
233	<td><nobr><b><tt id='l2h-3903' xml:id='l2h-3903' class="method">__unicode__</tt></b>(</nobr></td>
234	<td><var></var>)</td></tr></table></dt>
235	<dd>
236	A helper for the built-in <tt class="function">unicode()</tt> function. Returns the
237	header as a Unicode string.
238	</dl>
239
240	<P>
241	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
242	<td><nobr><b><tt id='l2h-3904' xml:id='l2h-3904' class="method">__eq__</tt></b>(</nobr></td>
243	<td><var>other</var>)</td></tr></table></dt>
244	<dd>
245	This method allows you to compare two <tt class="class">Header</tt> instances for equality.
246	</dl>
247
248	<P>
249	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
250	<td><nobr><b><tt id='l2h-3905' xml:id='l2h-3905' class="method">__ne__</tt></b>(</nobr></td>
251	<td><var>other</var>)</td></tr></table></dt>
252	<dd>
253	This method allows you to compare two <tt class="class">Header</tt> instances for inequality.
254	</dl>
255
256	<P>
257	The <tt class="module">email.Header</tt> module also provides the following
258	convenient functions.
259
260	<P>
261	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
262	<td><nobr><b><tt id='l2h-3906' xml:id='l2h-3906' class="function">decode_header</tt></b>(</nobr></td>
263	<td><var>header</var>)</td></tr></table></dt>
264	<dd>
265	Decode a message header value without converting the character set.
266	The header value is in <var>header</var>.
267
268	<P>
269	This function returns a list of <code>(decoded_string, charset)</code> pairs
270	containing each of the decoded parts of the header. <var>charset</var> is
271	<code>None</code> for non-encoded parts of the header, otherwise a lower
272	case string containing the name of the character set specified in the
273	encoded string.
274
275	<P>
276	Here's an example:
277
278	<P>
279	<div class="verbatim"><pre>
280	>>> from email.Header import decode_header
281	>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
282	[('p\xf6stal', 'iso-8859-1')]
283	</pre></div>
284	</dl>
285
286	<P>
287	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
288	<td><nobr><b><tt id='l2h-3907' xml:id='l2h-3907' class="function">make_header</tt></b>(</nobr></td>
289	<td><var>decoded_seq</var><big>[</big><var>, maxlinelen</var><big>[</big><var>,
290	header_name</var><big>[</big><var>, continuation_ws</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
291	<dd>
292	Create a <tt class="class">Header</tt> instance from a sequence of pairs as returned
293	by <tt class="function">decode_header()</tt>.
294
295	<P>
296	<tt class="function">decode_header()</tt> takes a header value string and returns a
297	sequence of pairs of the format <code>(decoded_string, charset)</code> where
298	<var>charset</var> is the name of the character set.
299
300	<P>
301	This function takes one of those sequence of pairs and returns a
302	<tt class="class">Header</tt> instance. Optional <var>maxlinelen</var>,
303	<var>header_name</var>, and <var>continuation_ws</var> are as in the
304	<tt class="class">Header</tt> constructor.
305	</dl>
306
307	<P>
308
309	<DIV CLASS="navigation">
310	<div class='online-navigation'>
311	<p></p><hr />
312	<table align="center" width="100%" cellpadding="0" cellspacing="2">
313	<tr>
314	<td class='online-navigation'><a rel="prev" title="12.2.4 Creating email and"
315	href="node588.html"><img src='../icons/previous.png'
316	border='0' height='32' alt='Previous Page' width='32' /></A></td>
317	<td class='online-navigation'><a rel="parent" title="12.2 email "
318	href="module-email.html"><img src='../icons/up.png'
319	border='0' height='32' alt='Up One Level' width='32' /></A></td>
320	<td class='online-navigation'><a rel="next" title="12.2.6 Representing character sets"
321	href="module-email.Charset.html"><img src='../icons/next.png'
322	border='0' height='32' alt='Next Page' width='32' /></A></td>
323	<td align="center" width="100%">Python Library Reference</td>
324	<td class='online-navigation'><a rel="contents" title="Table of Contents"
325	href="contents.html"><img src='../icons/contents.png'
326	border='0' height='32' alt='Contents' width='32' /></A></td>
327	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
328	border='0' height='32' alt='Module Index' width='32' /></a></td>
329	<td class='online-navigation'><a rel="index" title="Index"
330	href="genindex.html"><img src='../icons/index.png'
331	border='0' height='32' alt='Index' width='32' /></A></td>
332	</tr></table>
333	<div class='online-navigation'>
334	<b class="navlabel">Previous:</b>
335	<a class="sectref" rel="prev" href="node588.html">12.2.4 Creating email and</A>
336	<b class="navlabel">Up:</b>
337	<a class="sectref" rel="parent" href="module-email.html">12.2 email </A>
338	<b class="navlabel">Next:</b>
339	<a class="sectref" rel="next" href="module-email.Charset.html">12.2.6 Representing character sets</A>
340	</div>
341	</div>
342	<hr />
343	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
344	</DIV>
345	<!--End of Navigation Panel-->
346	<ADDRESS>
347	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
348	</ADDRESS>
349	</BODY>
350	</HTML>