Skip to content

Latest commit

 

History

History
197 lines (139 loc) · 8.53 KB

email.header.rst

File metadata and controls

197 lines (139 loc) · 8.53 KB
Raw

:mod:`email.header`: Internationalized headers

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

Source code: :source:`Lib/email/header.py`

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:`~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:

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

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

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

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?=')
      [(b'p\xf6stal', 'iso-8859-1')]



.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, 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.