← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.12-docs-html/_sources/library/email.header.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

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