: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

:class:`Header` class and assign the field in the :class:`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::

   >>> from email.message import Message

   >>> from email.header import Header

   >>> msg = Message()

   >>> h = Header('p\xf6stal', 'iso-8859-1')

   >>> msg['Subject'] = h

   >>> print msg.as_string()

   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

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

.. versionadded:: 2.2.2

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

.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])

   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

   :meth:`append` method calls.  *s* may be a byte string or a Unicode string, but

   see the :meth:`append` documentation for semantics.

   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.

   The maximum line length can be specified explicit via *maxlinelen*.  For

   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.

   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.

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

   .. method:: append(s[, charset[, errors]])

      Append the string *s* to the MIME header.

      Optional *charset*, if given, should be a :class:`Charset` instance (see

      :mod:`email.charset`) or the name of a character set, which will be

      converted to a :class:`Charset` instance.  A value of ``None`` (the

      default) means that the *charset* given in the constructor is used.

      *s* may be a byte string or a Unicode string.  If it is a byte string

      (i.e.  ``isinstance(s, str)`` is true), 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.

      If *s* is a Unicode string, then *charset* is a hint specifying the

      character set of the characters in the string.  In this case, when

      producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the

      Unicode string will be encoded using the following charsets in order:

      ``us-ascii``, the *charset* hint, ``utf-8``.  The first character set to

      not provoke a :exc:`UnicodeError` is used.

      Optional *errors* is passed through to any :func:`unicode` or

      :func:`ustr.encode` call, and defaults to "strict".

   .. method:: encode([splitchars])

      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.

   The :class:`Header` class also provides a number of methods to support

   standard operators and built-in functions.

   .. method:: __str__()

      A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.

   .. method:: __unicode__()

      A helper for the built-in :func:`unicode` function.  Returns the header as

      a Unicode string.

   .. method:: __eq__(other)

      This method allows you to compare two :class:`Header` instances for

      equality.

   .. method:: __ne__(other)

      This method allows you to compare two :class:`Header` instances for

      inequality.

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

.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])

   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.

   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.