blob: c426c952de21b1069bb4b262607442b6cf53ecfa [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`email`: Internationalized headers
2---------------------------------------
3
4.. module:: email.header
5 :synopsis: Representing non-ASCII headers
6
7
8:rfc:`2822` is the base standard that describes the format of email messages.
9It derives from the older :rfc:`822` standard which came into widespread use at
10a time when most email was composed of ASCII characters only. :rfc:`2822` is a
11specification written assuming email contains only 7-bit ASCII characters.
12
13Of course, as email has been deployed worldwide, it has become
14internationalized, such that language specific character sets can now be used in
15email messages. The base standard still requires email messages to be
16transferred using only 7-bit ASCII characters, so a slew of RFCs have been
17written 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
20in its :mod:`email.header` and :mod:`email.charset` modules.
21
22If 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
25instance of :class:`Header` instead of using a string for the header value.
26Import the :class:`Header` class from the :mod:`email.header` module. For
27example::
28
29 >>> from email.message import Message
30 >>> from email.header import Header
31 >>> msg = Message()
32 >>> h = Header('p\xf6stal', 'iso-8859-1')
33 >>> msg['Subject'] = h
Georg Brandl6911e3c2007-09-04 07:15:32 +000034 >>> print(msg.as_string())
Georg Brandl116aa622007-08-15 14:28:22 +000035 Subject: =?iso-8859-1?q?p=F6stal?=
36
37
38
39Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
40character? We did this by creating a :class:`Header` instance and passing in
41the character set that the byte string was encoded in. When the subsequent
42:class:`Message` instance was flattened, the :mailheader:`Subject` field was
43properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
44using the embedded ISO-8859-1 character.
45
Georg Brandl116aa622007-08-15 14:28:22 +000046Here is the :class:`Header` class description:
47
48
49.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
50
51 Create a MIME-compliant header that can contain strings in different character
52 sets.
53
54 Optional *s* is the initial header value. If ``None`` (the default), the
55 initial header value is not set. You can later append to the header with
56 :meth:`append` method calls. *s* may be a byte string or a Unicode string, but
57 see the :meth:`append` documentation for semantics.
58
59 Optional *charset* serves two purposes: it has the same meaning as the *charset*
60 argument to the :meth:`append` method. It also sets the default character set
61 for all subsequent :meth:`append` calls that omit the *charset* argument. If
62 *charset* is not provided in the constructor (the default), the ``us-ascii``
63 character set is used both as *s*'s initial charset and as the default for
64 subsequent :meth:`append` calls.
65
66 The maximum line length can be specified explicit via *maxlinelen*. For
67 splitting the first line to a shorter value (to account for the field header
68 which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
69 field in *header_name*. The default *maxlinelen* is 76, and the default value
70 for *header_name* is ``None``, meaning it is not taken into account for the
71 first line of a long, split header.
72
73 Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
74 and is usually either a space or a hard tab character. This character will be
75 prepended to continuation lines.
76
77Optional *errors* is passed straight through to the :meth:`append` method.
78
79
80.. method:: Header.append(s[, charset[, errors]])
81
82 Append the string *s* to the MIME header.
83
84 Optional *charset*, if given, should be a :class:`Charset` instance (see
85 :mod:`email.charset`) or the name of a character set, which will be converted to
86 a :class:`Charset` instance. A value of ``None`` (the default) means that the
87 *charset* given in the constructor is used.
88
89 *s* may be a byte string or a Unicode string. If it is a byte string (i.e.
90 ``isinstance(s, str)`` is true), then *charset* is the encoding of that byte
91 string, and a :exc:`UnicodeError` will be raised if the string cannot be decoded
92 with that character set.
93
94 If *s* is a Unicode string, then *charset* is a hint specifying the character
95 set of the characters in the string. In this case, when producing an
96 :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
97 be encoded using the following charsets in order: ``us-ascii``, the *charset*
98 hint, ``utf-8``. The first character set to not provoke a :exc:`UnicodeError`
99 is used.
100
101 Optional *errors* is passed through to any :func:`unicode` or
102 :func:`ustr.encode` call, and defaults to "strict".
103
104
105.. method:: Header.encode([splitchars])
106
107 Encode a message header into an RFC-compliant format, possibly wrapping long
108 lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
109 Optional *splitchars* is a string containing characters to split long ASCII
110 lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
111 This doesn't affect :rfc:`2047` encoded lines.
112
113The :class:`Header` class also provides a number of methods to support standard
114operators and built-in functions.
115
116
117.. method:: Header.__str__()
118
119 A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
120
121
122.. method:: Header.__unicode__()
123
124 A helper for the built-in :func:`unicode` function. Returns the header as a
125 Unicode string.
126
127
128.. method:: Header.__eq__(other)
129
130 This method allows you to compare two :class:`Header` instances for equality.
131
132
133.. method:: Header.__ne__(other)
134
135 This method allows you to compare two :class:`Header` instances for inequality.
136
137The :mod:`email.header` module also provides the following convenient functions.
138
139
140.. function:: decode_header(header)
141
142 Decode a message header value without converting the character set. The header
143 value is in *header*.
144
145 This function returns a list of ``(decoded_string, charset)`` pairs containing
146 each of the decoded parts of the header. *charset* is ``None`` for non-encoded
147 parts of the header, otherwise a lower case string containing the name of the
148 character set specified in the encoded string.
149
150 Here's an example::
151
152 >>> from email.header import decode_header
153 >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
154 [('p\xf6stal', 'iso-8859-1')]
155
156
157.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
158
159 Create a :class:`Header` instance from a sequence of pairs as returned by
160 :func:`decode_header`.
161
162 :func:`decode_header` takes a header value string and returns a sequence of
163 pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
164 the character set.
165
166 This function takes one of those sequence of pairs and returns a :class:`Header`
167 instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
168 the :class:`Header` constructor.
169