email.header.rst 7.98 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
:mod:`email`: Internationalized headers
---------------------------------------

.. module:: email.header
   :synopsis: Representing non-ASCII headers


: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 :mod:`email` package supports these standards
in its :mod:`email.header` and :mod:`email.charset` modules.

If you want to include non-ASCII characters in your email headers, say in the
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
24 25 26 27
:class:`Header` class and assign the field in the :class:`~email.message.Message`
object to an instance of :class:`Header` instead of using a string for the header
value.  Import the :class:`Header` class from the :mod:`email.header` module.
For example::
28 29 30 31 32 33

   >>> from email.message import Message
   >>> from email.header import Header
   >>> msg = Message()
   >>> h = Header('p\xf6stal', 'iso-8859-1')
   >>> msg['Subject'] = h
34
   >>> print(msg.as_string())
35 36 37 38 39 40 41
   Subject: =?iso-8859-1?q?p=F6stal?=



Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
character?  We did this by creating a :class:`Header` instance and passing in
the character set that the byte string was encoded in.  When the subsequent
42 43 44
:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
header using the embedded ISO-8859-1 character.
45 46 47 48

Here is the :class:`Header` class description:


49
.. class:: Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')
50 51 52 53 54 55

   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
56 57
   :meth:`append` method calls.  *s* may be an instance of :class:`bytes` or
   :class:`str`, but see the :meth:`append` documentation for semantics.
58 59 60 61 62 63 64 65

   Optional *charset* serves two purposes: it has the same meaning as the *charset*
   argument to the :meth:`append` method.  It also sets the default character set
   for all subsequent :meth:`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 :meth:`append` calls.

R. David Murray's avatar
R. David Murray committed
66
   The maximum line length can be specified explicitly via *maxlinelen*.  For
67 68 69 70 71 72
   splitting the first line to a shorter value (to account for the field header
   which isn't included in *s*, e.g. :mailheader:`Subject`) 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.

73 74 75 76
   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.  *continuation_ws*
   defaults to a single space character.
77

78
   Optional *errors* is passed straight through to the :meth:`append` method.
79 80


81
   .. method:: append(s, charset=None, errors='strict')
82

83
      Append the string *s* to the MIME header.
84

85 86 87 88 89
      Optional *charset*, if given, should be a :class:`~email.charset.Charset`
      instance (see :mod:`email.charset`) or the name of a character set, which
      will be converted to a :class:`~email.charset.Charset` instance.  A value
      of ``None`` (the default) means that the *charset* given in the constructor
      is used.
90

91 92 93 94
      *s* may be an instance of :class:`bytes` or :class:`str`.  If it is an
      instance of :class:`bytes`, then *charset* is the encoding of that byte
      string, and a :exc:`UnicodeError` will be raised if the string cannot be
      decoded with that character set.
95

96
      If *s* is an instance of :class:`str`, then *charset* is a hint specifying
97 98 99 100 101 102 103 104 105
      the character set of the characters in the string.

      In either case, when producing an :rfc:`2822`\ -compliant header using
      :rfc:`2047` rules, the string will be encoded using the output codec of
      the charset.  If the string cannot be encoded using the output codec, a
      UnicodeError will be raised.

      Optional *errors* is passed as the errors argument to the decode call
      if *s* is a byte string.
106 107


108
   .. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
109

110 111 112 113 114
      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.
115

116 117 118
      *maxlinelen*, if given, overrides the instance's value for the maximum
      line length.

119 120 121 122 123
      *linesep* specifies the characters used to separate the lines of the
      folded header.  It defaults to the most useful value for Python
      application code (``\n``), but ``\r\n`` can be specified in order
      to produce headers with RFC-compliant line separators.

Georg Brandl's avatar
Georg Brandl committed
124 125
      .. versionchanged:: 3.2
         Added the *linesep* argument.
126

127

128 129
   The :class:`Header` class also provides a number of methods to support
   standard operators and built-in functions.
130

131
   .. method:: __str__()
132

133 134 135 136 137 138 139 140
      Returns an approximation of the :class:`Header` as a string, using an
      unlimited line length.  All pieces are converted to unicode using the
      specified encoding and joined together appropriately.  Any pieces with a
      charset of `unknown-8bit` are decoded as `ASCII` using the `replace`
      error handler.

      .. versionchanged:: 3.2
         Added handling for the `unknown-8bit` charset.
141

142

143
   .. method:: __eq__(other)
144

145 146
      This method allows you to compare two :class:`Header` instances for
      equality.
147 148


149
   .. method:: __ne__(other)
150

151 152
      This method allows you to compare two :class:`Header` instances for
      inequality.
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173

The :mod:`email.header` module also provides the following convenient functions.


.. function:: decode_header(header)

   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')]


174
.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
175 176 177 178 179 180 181 182

   Create a :class:`Header` instance from a sequence of pairs as returned by
   :func:`decode_header`.

   :func:`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.

183 184 185
   This function takes one of those sequence of pairs and returns a
   :class:`Header` instance.  Optional *maxlinelen*, *header_name*, and
   *continuation_ws* are as in the :class:`Header` constructor.
186