1:mod:`email.header`: Internationalized headers
2----------------------------------------------
3
4.. module:: email.header
5   :synopsis: Representing non-ASCII headers
6
7**Source code:** :source:`Lib/email/header.py`
8
9--------------
10
11This module is part of the legacy (``Compat32``) email API.  In the current API
12encoding and decoding of headers is handled transparently by the
13dictionary-like API of the :class:`~email.message.EmailMessage` class.  In
14addition to uses in legacy code, this module can be useful in applications that
15need to completely control the character sets used when encoding headers.
16
17The remaining text in this section is the original documentation of the module.
18
19:rfc:`2822` is the base standard that describes the format of email messages.
20It derives from the older :rfc:`822` standard which came into widespread use at
21a time when most email was composed of ASCII characters only.  :rfc:`2822` is a
22specification written assuming email contains only 7-bit ASCII characters.
23
24Of course, as email has been deployed worldwide, it has become
25internationalized, such that language specific character sets can now be used in
26email messages.  The base standard still requires email messages to be
27transferred using only 7-bit ASCII characters, so a slew of RFCs have been
28written describing how to encode email containing non-ASCII characters into
29:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
30:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
31in its :mod:`email.header` and :mod:`email.charset` modules.
32
33If you want to include non-ASCII characters in your email headers, say in the
34:mailheader:`Subject` or :mailheader:`To` fields, you should use the
35:class:`Header` class and assign the field in the :class:`~email.message.Message`
36object to an instance of :class:`Header` instead of using a string for the header
37value.  Import the :class:`Header` class from the :mod:`email.header` module.
38For example::
39
40   >>> from email.message import Message
41   >>> from email.header import Header
42   >>> msg = Message()
43   >>> h = Header('p\xf6stal', 'iso-8859-1')
44   >>> msg['Subject'] = h
45   >>> msg.as_string()
46   'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'
47
48
49
50Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
51character?  We did this by creating a :class:`Header` instance and passing in
52the character set that the byte string was encoded in.  When the subsequent
53:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
54field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
55header using the embedded ISO-8859-1 character.
56
57Here is the :class:`Header` class description:
58
59
60.. class:: Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')
61
62   Create a MIME-compliant header that can contain strings in different character
63   sets.
64
65   Optional *s* is the initial header value.  If ``None`` (the default), the
66   initial header value is not set.  You can later append to the header with
67   :meth:`append` method calls.  *s* may be an instance of :class:`bytes` or
68   :class:`str`, but see the :meth:`append` documentation for semantics.
69
70   Optional *charset* serves two purposes: it has the same meaning as the *charset*
71   argument to the :meth:`append` method.  It also sets the default character set
72   for all subsequent :meth:`append` calls that omit the *charset* argument.  If
73   *charset* is not provided in the constructor (the default), the ``us-ascii``
74   character set is used both as *s*'s initial charset and as the default for
75   subsequent :meth:`append` calls.
76
77   The maximum line length can be specified explicitly via *maxlinelen*.  For
78   splitting the first line to a shorter value (to account for the field header
79   which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
80   field in *header_name*.  The default *maxlinelen* is 76, and the default value
81   for *header_name* is ``None``, meaning it is not taken into account for the
82   first line of a long, split header.
83
84   Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding
85   whitespace, and is usually either a space or a hard tab character.  This
86   character will be prepended to continuation lines.  *continuation_ws*
87   defaults to a single space character.
88
89   Optional *errors* is passed straight through to the :meth:`append` method.
90
91
92   .. method:: append(s, charset=None, errors='strict')
93
94      Append the string *s* to the MIME header.
95
96      Optional *charset*, if given, should be a :class:`~email.charset.Charset`
97      instance (see :mod:`email.charset`) or the name of a character set, which
98      will be converted to a :class:`~email.charset.Charset` instance.  A value
99      of ``None`` (the default) means that the *charset* given in the constructor
100      is used.
101
102      *s* may be an instance of :class:`bytes` or :class:`str`.  If it is an
103      instance of :class:`bytes`, then *charset* is the encoding of that byte
104      string, and a :exc:`UnicodeError` will be raised if the string cannot be
105      decoded with that character set.
106
107      If *s* is an instance of :class:`str`, then *charset* is a hint specifying
108      the character set of the characters in the string.
109
110      In either case, when producing an :rfc:`2822`\ -compliant header using
111      :rfc:`2047` rules, the string will be encoded using the output codec of
112      the charset.  If the string cannot be encoded using the output codec, a
113      UnicodeError will be raised.
114
115      Optional *errors* is passed as the errors argument to the decode call
116      if *s* is a byte string.
117
118
119   .. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
120
121      Encode a message header into an RFC-compliant format, possibly wrapping
122      long lines and encapsulating non-ASCII parts in base64 or quoted-printable
123      encodings.
124
125      Optional *splitchars* is a string containing characters which should be
126      given extra weight by the splitting algorithm during normal header
127      wrapping.  This is in very rough support of :RFC:`2822`\'s 'higher level
128      syntactic breaks':  split points preceded by a splitchar are preferred
129      during line splitting, with the characters preferred in the order in
130      which they appear in the string.  Space and tab may be included in the
131      string to indicate whether preference should be given to one over the
132      other as a split point when other split chars do not appear in the line
133      being split.  Splitchars does not affect :RFC:`2047` encoded lines.
134
135      *maxlinelen*, if given, overrides the instance's value for the maximum
136      line length.
137
138      *linesep* specifies the characters used to separate the lines of the
139      folded header.  It defaults to the most useful value for Python
140      application code (``\n``), but ``\r\n`` can be specified in order
141      to produce headers with RFC-compliant line separators.
142
143      .. versionchanged:: 3.2
144         Added the *linesep* argument.
145
146
147   The :class:`Header` class also provides a number of methods to support
148   standard operators and built-in functions.
149
150   .. method:: __str__()
151
152      Returns an approximation of the :class:`Header` as a string, using an
153      unlimited line length.  All pieces are converted to unicode using the
154      specified encoding and joined together appropriately.  Any pieces with a
155      charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'``
156      error handler.
157
158      .. versionchanged:: 3.2
159         Added handling for the ``'unknown-8bit'`` charset.
160
161
162   .. method:: __eq__(other)
163
164      This method allows you to compare two :class:`Header` instances for
165      equality.
166
167
168   .. method:: __ne__(other)
169
170      This method allows you to compare two :class:`Header` instances for
171      inequality.
172
173The :mod:`email.header` module also provides the following convenient functions.
174
175
176.. function:: decode_header(header)
177
178   Decode a message header value without converting the character set. The header
179   value is in *header*.
180
181   This function returns a list of ``(decoded_string, charset)`` pairs containing
182   each of the decoded parts of the header.  *charset* is ``None`` for non-encoded
183   parts of the header, otherwise a lower case string containing the name of the
184   character set specified in the encoded string.
185
186   Here's an example::
187
188      >>> from email.header import decode_header
189      >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
190      [(b'p\xf6stal', 'iso-8859-1')]
191
192
193.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
194
195   Create a :class:`Header` instance from a sequence of pairs as returned by
196   :func:`decode_header`.
197
198   :func:`decode_header` takes a header value string and returns a sequence of
199   pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
200   the character set.
201
202   This function takes one of those sequence of pairs and returns a
203   :class:`Header` instance.  Optional *maxlinelen*, *header_name*, and
204   *continuation_ws* are as in the :class:`Header` constructor.
205
206