Move the 3k reST doc tree in place.

1 files changed, 171 insertions, 0 deletions

diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
new file mode 100644
index 0000000..0ecd35f
--- /dev/null
+++ b/Doc/library/email.header.rst
@@ -0,0 +1,171 @@
+: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:: Header.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:: Header.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:: Header.__str__()
+
+   A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.
+
+
+.. method:: Header.__unicode__()
+
+   A helper for the built-in :func:`unicode` function.  Returns the header as a
+   Unicode string.
+
+
+.. method:: Header.__eq__(other)
+
+   This method allows you to compare two :class:`Header` instances for equality.
+
+
+.. method:: Header.__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.
+