RFC 2822 is the base standard that describes the format of email
messages. It derives from the older RFC 822 standard which came
into widespread use at a time when most email was composed of ASCII
characters only. RFC 2822 is a specification written assuming email
contains only 7-bit ASCII characters.
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 RFC 2822-compliant format.
These RFCs include RFC 2045, RFC 2046, RFC 2047, and RFC 2231.
The email package supports these standards in its
email.header and email.charset modules.
If you want to include non-ASCII characters in your email headers,
say in the or fields, you should
use the Header class and assign the field in the
Message object to an instance of Header instead of
using a string for the header value. Import the Header class from the
email.header module. For example:
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=
Notice here how we wanted the field to contain a
non-ASCII character? We did this by creating a Header
instance and passing in the character set that the byte string was
encoded in. When the subsequent Message instance was
flattened, the field was properly RFC 2047
encoded. MIME-aware mail readers would show this header using the
embedded ISO-8859-1 character.
New in version 2.2.2.
Here is the Header class description:
class Header( |
[s[, charset[,
maxlinelen[, header_name[, continuation_ws[,
errors]]]]]]) |
-
Create a MIME-compliant header that can contain strings in different
character sets.
Optional s is the initial header value. If None (the
default), the initial header value is not set. You can later append
to the header with append() method calls. s may be a
byte string or a Unicode string, but see the append()
documentation for semantics.
Optional charset serves two purposes: it has the same meaning as
the charset argument to the append() method. It also
sets the default character set for all subsequent append()
calls that omit the charset argument. If charset is not
provided in the constructor (the default), the us-ascii
character set is used both as s's initial charset and as the
default for subsequent append() calls.
The maximum line length can be specified explicit via
maxlinelen. For splitting the first line to a shorter value (to
account for the field header which isn't included in s,
e.g. ) pass in the name of the field in
header_name. The default maxlinelen is 76, and the
default value for header_name is None , meaning it is not
taken into account for the first line of a long, split header.
Optional continuation_ws must be RFC 2822-compliant folding
whitespace, and is usually either a space or a hard tab character.
This character will be prepended to continuation lines.
Optional errors is passed straight through to the
append() method.
append( |
s[, charset[, errors]]) |
-
Append the string s to the MIME header.
Optional charset, if given, should be a Charset instance
(see email.charset) or the name of a character set, which
will be converted to a Charset instance. A value of
None (the default) means that the charset given in the
constructor is used.
s may be a byte string or a Unicode string. If it is a byte
string (i.e. isinstance(s, str) is true), then
charset is the encoding of that byte string, and a
UnicodeError will be raised if the string cannot be
decoded with that character set.
If s is a Unicode string, then charset is a hint
specifying the character set of the characters in the string. In this
case, when producing an RFC 2822-compliant header using RFC 2047
rules, the Unicode string will be encoded using the following charsets
in order: us-ascii , the charset hint, utf-8 . The
first character set to not provoke a UnicodeError is used.
Optional errors is passed through to any unicode() or
ustr.encode() call, and defaults to ``strict''.
-
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 splitchars is a string
containing characters to split long ASCII lines on, in rough support
of RFC 2822's highest level syntactic breaks. This doesn't
affect RFC 2047 encoded lines.
The Header class also provides a number of methods to support
standard operators and built-in functions.
-
A synonym for Header.encode(). Useful for
str(aHeader) .
-
A helper for the built-in unicode() function. Returns the
header as a Unicode string.
-
This method allows you to compare two Header instances for equality.
-
This method allows you to compare two Header instances for inequality.
The email.header module also provides the following
convenient functions.
-
Decode a message header value without converting the character set.
The header value is in header.
This function returns a list of (decoded_string, charset) pairs
containing each of the decoded parts of the header. charset is
None for non-encoded parts of the header, otherwise a lower
case string containing the name of the character set specified in the
encoded string.
Here's an example:
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[('p\xf6stal', 'iso-8859-1')]
make_header( |
decoded_seq[, maxlinelen[,
header_name[, continuation_ws]]]) |
-
Create a Header instance from a sequence of pairs as returned
by decode_header().
decode_header() takes a header value string and returns a
sequence of pairs of the format (decoded_string, charset) where
charset is the name of the character set.
This function takes one of those sequence of pairs and returns a
Header instance. Optional maxlinelen,
header_name, and continuation_ws are as in the
Header constructor.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|