/Doc/library/email.header.rst

  1: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:`~email.message.Message`
 25object to an instance of :class:`Header` instead of using a string for the header
 26value.  Import the :class:`Header` class from the :mod:`email.header` module.
 27For example::
 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
 34   >>> print msg.as_string()
 35   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:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
 43field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
 44header using the embedded ISO-8859-1 character.
 45
 46.. versionadded:: 2.2.2
 47
 48Here is the :class:`Header` class description:
 49
 50
 51.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
 52
 53   Create a MIME-compliant header that can contain strings in different character
 54   sets.
 55
 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.
 60
 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.
 67
 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.
 74
 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.
 78
 79   Optional *errors* is passed straight through to the :meth:`append` method.
 80
 81
 82   .. method:: append(s[, charset[, errors]])
 83
 84      Append the string *s* to the MIME header.
 85
 86      Optional *charset*, if given, should be a :class:`~email.charset.Charset`
 87      instance (see :mod:`email.charset`) or the name of a character set, which
 88      will be converted to a :class:`~email.charset.Charset` instance.  A value
 89      of ``None`` (the default) means that the *charset* given in the constructor
 90      is used.
 91
 92      *s* may be a byte string or a Unicode string.  If it is a byte string
 93      (i.e.  ``isinstance(s, str)`` is true), then *charset* is the encoding of
 94      that byte string, and a :exc:`UnicodeError` will be raised if the string
 95      cannot be decoded with that character set.
 96
 97      If *s* is a Unicode string, then *charset* is a hint specifying the
 98      character set of the characters in the string.  In this case, when
 99      producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
100      Unicode string will be encoded using the following charsets in order:
101      ``us-ascii``, the *charset* hint, ``utf-8``.  The first character set to
102      not provoke a :exc:`UnicodeError` is used.
103
104      Optional *errors* is passed through to any :func:`unicode` or
105      :func:`ustr.encode` call, and defaults to "strict".
106
107
108   .. method:: encode([splitchars])
109
110      Encode a message header into an RFC-compliant format, possibly wrapping
111      long lines and encapsulating non-ASCII parts in base64 or quoted-printable
112      encodings.  Optional *splitchars* is a string containing characters to
113      split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
114      level syntactic breaks*.  This doesn't affect :rfc:`2047` encoded lines.
115
116   The :class:`Header` class also provides a number of methods to support
117   standard operators and built-in functions.
118
119
120   .. method:: __str__()
121
122      A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.
123
124
125   .. method:: __unicode__()
126
127      A helper for the built-in :func:`unicode` function.  Returns the header as
128      a Unicode string.
129
130
131   .. method:: __eq__(other)
132
133      This method allows you to compare two :class:`Header` instances for
134      equality.
135
136
137   .. method:: __ne__(other)
138
139      This method allows you to compare two :class:`Header` instances for
140      inequality.
141
142The :mod:`email.header` module also provides the following convenient functions.
143
144
145.. function:: decode_header(header)
146
147   Decode a message header value without converting the character set. The header
148   value is in *header*.
149
150   This function returns a list of ``(decoded_string, charset)`` pairs containing
151   each of the decoded parts of the header.  *charset* is ``None`` for non-encoded
152   parts of the header, otherwise a lower case string containing the name of the
153   character set specified in the encoded string.
154
155   Here's an example::
156
157      >>> from email.header import decode_header
158      >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
159      [('p\xf6stal', 'iso-8859-1')]
160
161
162.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
163
164   Create a :class:`Header` instance from a sequence of pairs as returned by
165   :func:`decode_header`.
166
167   :func:`decode_header` takes a header value string and returns a sequence of
168   pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
169   the character set.
170
171   This function takes one of those sequence of pairs and returns a :class:`Header`
172   instance.  Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
173   the :class:`Header` constructor.
174