/Doc/library/email.header.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 174 lines · 119 code · 55 blank · 0 comment · 0 complexity · 0964662f74899d8086192e13f4e9c01a MD5 · raw file

  1. :mod:`email`: Internationalized headers
  2. ---------------------------------------
  3. .. module:: email.header
  4. :synopsis: Representing non-ASCII headers
  5. :rfc:`2822` is the base standard that describes the format of email messages.
  6. It derives from the older :rfc:`822` standard which came into widespread use at
  7. a time when most email was composed of ASCII characters only. :rfc:`2822` is a
  8. specification written assuming email contains only 7-bit ASCII characters.
  9. Of course, as email has been deployed worldwide, it has become
  10. internationalized, such that language specific character sets can now be used in
  11. email messages. The base standard still requires email messages to be
  12. transferred using only 7-bit ASCII characters, so a slew of RFCs have been
  13. written describing how to encode email containing non-ASCII characters into
  14. :rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
  15. :rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
  16. in its :mod:`email.header` and :mod:`email.charset` modules.
  17. If you want to include non-ASCII characters in your email headers, say in the
  18. :mailheader:`Subject` or :mailheader:`To` fields, you should use the
  19. :class:`Header` class and assign the field in the :class:`~email.message.Message`
  20. object to an instance of :class:`Header` instead of using a string for the header
  21. value. Import the :class:`Header` class from the :mod:`email.header` module.
  22. For example::
  23. >>> from email.message import Message
  24. >>> from email.header import Header
  25. >>> msg = Message()
  26. >>> h = Header('p\xf6stal', 'iso-8859-1')
  27. >>> msg['Subject'] = h
  28. >>> print msg.as_string()
  29. Subject: =?iso-8859-1?q?p=F6stal?=
  30. Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
  31. character? We did this by creating a :class:`Header` instance and passing in
  32. the character set that the byte string was encoded in. When the subsequent
  33. :class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
  34. field was properly :rfc:`2047` encoded. MIME-aware mail readers would show this
  35. header using the embedded ISO-8859-1 character.
  36. .. versionadded:: 2.2.2
  37. Here is the :class:`Header` class description:
  38. .. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
  39. Create a MIME-compliant header that can contain strings in different character
  40. sets.
  41. Optional *s* is the initial header value. If ``None`` (the default), the
  42. initial header value is not set. You can later append to the header with
  43. :meth:`append` method calls. *s* may be a byte string or a Unicode string, but
  44. see the :meth:`append` documentation for semantics.
  45. Optional *charset* serves two purposes: it has the same meaning as the *charset*
  46. argument to the :meth:`append` method. It also sets the default character set
  47. for all subsequent :meth:`append` calls that omit the *charset* argument. If
  48. *charset* is not provided in the constructor (the default), the ``us-ascii``
  49. character set is used both as *s*'s initial charset and as the default for
  50. subsequent :meth:`append` calls.
  51. The maximum line length can be specified explicit via *maxlinelen*. For
  52. splitting the first line to a shorter value (to account for the field header
  53. which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
  54. field in *header_name*. The default *maxlinelen* is 76, and the default value
  55. for *header_name* is ``None``, meaning it is not taken into account for the
  56. first line of a long, split header.
  57. Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
  58. and is usually either a space or a hard tab character. This character will be
  59. prepended to continuation lines.
  60. Optional *errors* is passed straight through to the :meth:`append` method.
  61. .. method:: append(s[, charset[, errors]])
  62. Append the string *s* to the MIME header.
  63. Optional *charset*, if given, should be a :class:`~email.charset.Charset`
  64. instance (see :mod:`email.charset`) or the name of a character set, which
  65. will be converted to a :class:`~email.charset.Charset` instance. A value
  66. of ``None`` (the default) means that the *charset* given in the constructor
  67. is used.
  68. *s* may be a byte string or a Unicode string. If it is a byte string
  69. (i.e. ``isinstance(s, str)`` is true), then *charset* is the encoding of
  70. that byte string, and a :exc:`UnicodeError` will be raised if the string
  71. cannot be decoded with that character set.
  72. If *s* is a Unicode string, then *charset* is a hint specifying the
  73. character set of the characters in the string. In this case, when
  74. producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
  75. Unicode string will be encoded using the following charsets in order:
  76. ``us-ascii``, the *charset* hint, ``utf-8``. The first character set to
  77. not provoke a :exc:`UnicodeError` is used.
  78. Optional *errors* is passed through to any :func:`unicode` or
  79. :func:`ustr.encode` call, and defaults to "strict".
  80. .. method:: encode([splitchars])
  81. Encode a message header into an RFC-compliant format, possibly wrapping
  82. long lines and encapsulating non-ASCII parts in base64 or quoted-printable
  83. encodings. Optional *splitchars* is a string containing characters to
  84. split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
  85. level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines.
  86. The :class:`Header` class also provides a number of methods to support
  87. standard operators and built-in functions.
  88. .. method:: __str__()
  89. A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
  90. .. method:: __unicode__()
  91. A helper for the built-in :func:`unicode` function. Returns the header as
  92. a Unicode string.
  93. .. method:: __eq__(other)
  94. This method allows you to compare two :class:`Header` instances for
  95. equality.
  96. .. method:: __ne__(other)
  97. This method allows you to compare two :class:`Header` instances for
  98. inequality.
  99. The :mod:`email.header` module also provides the following convenient functions.
  100. .. function:: decode_header(header)
  101. Decode a message header value without converting the character set. The header
  102. value is in *header*.
  103. This function returns a list of ``(decoded_string, charset)`` pairs containing
  104. each of the decoded parts of the header. *charset* is ``None`` for non-encoded
  105. parts of the header, otherwise a lower case string containing the name of the
  106. character set specified in the encoded string.
  107. Here's an example::
  108. >>> from email.header import decode_header
  109. >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
  110. [('p\xf6stal', 'iso-8859-1')]
  111. .. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
  112. Create a :class:`Header` instance from a sequence of pairs as returned by
  113. :func:`decode_header`.
  114. :func:`decode_header` takes a header value string and returns a sequence of
  115. pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
  116. the character set.
  117. This function takes one of those sequence of pairs and returns a :class:`Header`
  118. instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
  119. the :class:`Header` constructor.