1
:mod:`email`: Internationalized headers
2
---------------------------------------
4
.. module:: email.header
5
:synopsis: Representing non-ASCII headers
8
:rfc:`2822` is the base standard that describes the format of email messages.
9
It derives from the older :rfc:`822` standard which came into widespread use at
10
a time when most email was composed of ASCII characters only. :rfc:`2822` is a
11
specification written assuming email contains only 7-bit ASCII characters.
13
Of course, as email has been deployed worldwide, it has become
14
internationalized, such that language specific character sets can now be used in
15
email messages. The base standard still requires email messages to be
16
transferred using only 7-bit ASCII characters, so a slew of RFCs have been
17
written describing how to encode email containing non-ASCII characters into
18
:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
19
:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
20
in its :mod:`email.header` and :mod:`email.charset` modules.
22
If you want to include non-ASCII characters in your email headers, say in the
23
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
24
:class:`Header` class and assign the field in the :class:`Message` object to an
25
instance of :class:`Header` instead of using a string for the header value.
26
Import the :class:`Header` class from the :mod:`email.header` module. For
29
>>> from email.message import Message
30
>>> from email.header import Header
32
>>> h = Header('p\xf6stal', 'iso-8859-1')
33
>>> msg['Subject'] = h
34
>>> print msg.as_string()
35
Subject: =?iso-8859-1?q?p=F6stal?=
39
Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
40
character? We did this by creating a :class:`Header` instance and passing in
41
the character set that the byte string was encoded in. When the subsequent
42
:class:`Message` instance was flattened, the :mailheader:`Subject` field was
43
properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
44
using the embedded ISO-8859-1 character.
46
.. versionadded:: 2.2.2
48
Here is the :class:`Header` class description:
51
.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
53
Create a MIME-compliant header that can contain strings in different character
56
Optional *s* is the initial header value. If ``None`` (the default), the
57
initial header value is not set. You can later append to the header with
58
:meth:`append` method calls. *s* may be a byte string or a Unicode string, but
59
see the :meth:`append` documentation for semantics.
61
Optional *charset* serves two purposes: it has the same meaning as the *charset*
62
argument to the :meth:`append` method. It also sets the default character set
63
for all subsequent :meth:`append` calls that omit the *charset* argument. If
64
*charset* is not provided in the constructor (the default), the ``us-ascii``
65
character set is used both as *s*'s initial charset and as the default for
66
subsequent :meth:`append` calls.
68
The maximum line length can be specified explicit via *maxlinelen*. For
69
splitting the first line to a shorter value (to account for the field header
70
which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
71
field in *header_name*. The default *maxlinelen* is 76, and the default value
72
for *header_name* is ``None``, meaning it is not taken into account for the
73
first line of a long, split header.
75
Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
76
and is usually either a space or a hard tab character. This character will be
77
prepended to continuation lines.
79
Optional *errors* is passed straight through to the :meth:`append` method.
82
.. method:: append(s[, charset[, errors]])
84
Append the string *s* to the MIME header.
86
Optional *charset*, if given, should be a :class:`Charset` instance (see
87
:mod:`email.charset`) or the name of a character set, which will be
88
converted to a :class:`Charset` instance. A value of ``None`` (the
89
default) means that the *charset* given in the constructor is used.
91
*s* may be a byte string or a Unicode string. If it is a byte string
92
(i.e. ``isinstance(s, str)`` is true), then *charset* is the encoding of
93
that byte string, and a :exc:`UnicodeError` will be raised if the string
94
cannot be decoded with that character set.
96
If *s* is a Unicode string, then *charset* is a hint specifying the
97
character set of the characters in the string. In this case, when
98
producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
99
Unicode string will be encoded using the following charsets in order:
100
``us-ascii``, the *charset* hint, ``utf-8``. The first character set to
101
not provoke a :exc:`UnicodeError` is used.
103
Optional *errors* is passed through to any :func:`unicode` or
104
:func:`ustr.encode` call, and defaults to "strict".
107
.. method:: encode([splitchars])
109
Encode a message header into an RFC-compliant format, possibly wrapping
110
long lines and encapsulating non-ASCII parts in base64 or quoted-printable
111
encodings. Optional *splitchars* is a string containing characters to
112
split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
113
level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines.
115
The :class:`Header` class also provides a number of methods to support
116
standard operators and built-in functions.
119
.. method:: __str__()
121
A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
124
.. method:: __unicode__()
126
A helper for the built-in :func:`unicode` function. Returns the header as
130
.. method:: __eq__(other)
132
This method allows you to compare two :class:`Header` instances for
136
.. method:: __ne__(other)
138
This method allows you to compare two :class:`Header` instances for
141
The :mod:`email.header` module also provides the following convenient functions.
144
.. function:: decode_header(header)
146
Decode a message header value without converting the character set. The header
147
value is in *header*.
149
This function returns a list of ``(decoded_string, charset)`` pairs containing
150
each of the decoded parts of the header. *charset* is ``None`` for non-encoded
151
parts of the header, otherwise a lower case string containing the name of the
152
character set specified in the encoded string.
156
>>> from email.header import decode_header
157
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
158
[('p\xf6stal', 'iso-8859-1')]
161
.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
163
Create a :class:`Header` instance from a sequence of pairs as returned by
164
:func:`decode_header`.
166
:func:`decode_header` takes a header value string and returns a sequence of
167
pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
170
This function takes one of those sequence of pairs and returns a :class:`Header`
171
instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
172
the :class:`Header` constructor.