rest25/library/email.header.rst => rest262/library/email.header.rst
n1+:mod:`email`: Internationalized headers
2+---------------------------------------
3+ 
1.. module:: email.header
2   :synopsis: Representing non-ASCII headers
3
4
5:rfc:`2822` is the base standard that describes the format of email messages.
6It derives from the older :rfc:`822` standard which came into widespread use at
7a time when most email was composed of ASCII characters only.  :rfc:`2822` is a
8specification written assuming email contains only 7-bit ASCII characters.
68   field in *header_name*.  The default *maxlinelen* is 76, and the default value
69   for *header_name* is ``None``, meaning it is not taken into account for the
70   first line of a long, split header.
71
72   Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
73   and is usually either a space or a hard tab character. This character will be
74   prepended to continuation lines.
75
n76-Optional *errors* is passed straight through to the :meth:`append` method.
n79+   Optional *errors* is passed straight through to the :meth:`append` method.
77
78
n79-.. method:: Header.append(s[, charset[, errors]])
n82+   .. method:: append(s[, charset[, errors]])
80
n81-   Append the string *s* to the MIME header.
n84+      Append the string *s* to the MIME header.
82
n83-   Optional *charset*, if given, should be a :class:`Charset` instance (see
n86+      Optional *charset*, if given, should be a :class:`Charset` instance (see
84-   :mod:`email.charset`) or the name of a character set, which will be converted to
87+      :mod:`email.charset`) or the name of a character set, which will be
85-   a :class:`Charset` instance.  A value of ``None`` (the default) means that the
88+      converted to a :class:`Charset` instance.  A value of ``None`` (the
86-   *charset* given in the constructor is used.
89+      default) means that the *charset* given in the constructor is used.
87
n88-   *s* may be a byte string or a Unicode string.  If it is a byte string (i.e.
n91+      *s* may be a byte string or a Unicode string.  If it is a byte string
89-   ``isinstance(s, str)`` is true), then *charset* is the encoding of that byte
92+      (i.e.  ``isinstance(s, str)`` is true), then *charset* is the encoding of
90-   string, and a :exc:`UnicodeError` will be raised if the string cannot be decoded
93+      that byte string, and a :exc:`UnicodeError` will be raised if the string
91-   with that character set.
94+      cannot be decoded with that character set.
92
n93-   If *s* is a Unicode string, then *charset* is a hint specifying the character
n96+      If *s* is a Unicode string, then *charset* is a hint specifying the
94-   set of the characters in the string.  In this case, when producing an
97+      character set of the characters in the string.  In this case, when
95-   :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the Unicode string will
98+      producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
96-   be encoded using the following charsets in order: ``us-ascii``, the *charset*
99+      Unicode string will be encoded using the following charsets in order:
97-   hint, ``utf-8``.  The first character set to not provoke a :exc:`UnicodeError`
100+      ``us-ascii``, the *charset* hint, ``utf-8``.  The first character set to
98-   is used.
101+      not provoke a :exc:`UnicodeError` is used.
99
n100-   Optional *errors* is passed through to any :func:`unicode` or
n103+      Optional *errors* is passed through to any :func:`unicode` or
101-   :func:`ustr.encode` call, and defaults to "strict".
104+      :func:`ustr.encode` call, and defaults to "strict".
102
103
n104-.. method:: Header.encode([splitchars])
n107+   .. method:: encode([splitchars])
105
n106-   Encode a message header into an RFC-compliant format, possibly wrapping long
n109+      Encode a message header into an RFC-compliant format, possibly wrapping
107-   lines and encapsulating non-ASCII parts in base64 or quoted-printable encodings.
110+      long lines and encapsulating non-ASCII parts in base64 or quoted-printable
108-   Optional *splitchars* is a string containing characters to split long ASCII
111+      encodings.  Optional *splitchars* is a string containing characters to
109-   lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*.
112+      split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
110-   This doesn't affect :rfc:`2047` encoded lines.
113+      level syntactic breaks*.  This doesn't affect :rfc:`2047` encoded lines.
111
n112-The :class:`Header` class also provides a number of methods to support standard
n115+   The :class:`Header` class also provides a number of methods to support
113-operators and built-in functions.
116+   standard operators and built-in functions.
114
115
n116-.. method:: Header.__str__()
n119+   .. method:: __str__()
117
n118-   A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.
n121+      A synonym for :meth:`Header.encode`.  Useful for ``str(aHeader)``.
119
120
n121-.. method:: Header.__unicode__()
n124+   .. method:: __unicode__()
122
n123-   A helper for the built-in :func:`unicode` function.  Returns the header as a
n126+      A helper for the built-in :func:`unicode` function.  Returns the header as
124-   Unicode string.
127+      a Unicode string.
125
126
n127-.. method:: Header.__eq__(other)
n130+   .. method:: __eq__(other)
128
n129-   This method allows you to compare two :class:`Header` instances for equality.
n132+      This method allows you to compare two :class:`Header` instances for
133+      equality.
130
131
n132-.. method:: Header.__ne__(other)
n136+   .. method:: __ne__(other)
133
t134-   This method allows you to compare two :class:`Header` instances for inequality.
t138+      This method allows you to compare two :class:`Header` instances for
139+      inequality.
135
136The :mod:`email.header` module also provides the following convenient functions.
137
138
139.. function:: decode_header(header)
140
141   Decode a message header value without converting the character set. The header
142   value is in *header*.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op