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 11 This module is part of the legacy (``Compat32``) email API. In the current API 12 encoding and decoding of headers is handled transparently by the 13 dictionary-like API of the :class:`~email.message.EmailMessage` class. In 14 addition to uses in legacy code, this module can be useful in applications that 15 need to completely control the character sets used when encoding headers. 16 17 The 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. 20 It derives from the older :rfc:`822` standard which came into widespread use at 21 a time when most email was composed of ASCII characters only. :rfc:`2822` is a 22 specification written assuming email contains only 7-bit ASCII characters. 23 24 Of course, as email has been deployed worldwide, it has become 25 internationalized, such that language specific character sets can now be used in 26 email messages. The base standard still requires email messages to be 27 transferred using only 7-bit ASCII characters, so a slew of RFCs have been 28 written 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 31 in its :mod:`email.header` and :mod:`email.charset` modules. 32 33 If 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` 36 object to an instance of :class:`Header` instead of using a string for the header 37 value. Import the :class:`Header` class from the :mod:`email.header` module. 38 For 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 50 Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII 51 character? We did this by creating a :class:`Header` instance and passing in 52 the character set that the byte string was encoded in. When the subsequent 53 :class:`~email.message.Message` instance was flattened, the :mailheader:`Subject` 54 field was properly :rfc:`2047` encoded. MIME-aware mail readers would show this 55 header using the embedded ISO-8859-1 character. 56 57 Here 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 173 The :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
