Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/emailheaders.tex @ 27998:e27f58a50737 legacy-trunk

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