Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/emailparser.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 3f90a93ff5d0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
1 \declaremodule{standard}{email.parser}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
2 \modulesynopsis{Parse flat text email messages to produce a message
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
3 object structure.}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
4
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
5 Message object structures can be created in one of two ways: they can be
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
6 created from whole cloth by instantiating \class{Message} objects and
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
7 stringing them together via \method{attach()} and
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
8 \method{set_payload()} calls, or they can be created by parsing a flat text
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
9 representation of the email message.
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
10
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
11 The \module{email} package provides a standard parser that understands
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
12 most email document structures, including MIME documents. You can
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
13 pass the parser a string or a file object, and the parser will return
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
14 to you the root \class{Message} instance of the object structure. For
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
15 simple, non-MIME messages the payload of this root object will likely
20459
c68d1855daa9 Fix a few usage and style-guide conformance issues.
Fred Drake <fdrake@acm.org>
parents: 20374
diff changeset
16 be a string containing the text of the message. For MIME
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
17 messages, the root object will return \code{True} from its
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
18 \method{is_multipart()} method, and the subparts can be accessed via
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
19 the \method{get_payload()} and \method{walk()} methods.
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
20
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
21 There are actually two parser interfaces available for use, the classic
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
22 \class{Parser} API and the incremental \class{FeedParser} API. The classic
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
23 \class{Parser} API is fine if you have the entire text of the message in
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
24 memory as a string, or if the entire message lives in a file on the file
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
25 system. \class{FeedParser} is more appropriate for when you're reading the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
26 message from a stream which might block waiting for more input (e.g. reading
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
27 an email message from a socket). The \class{FeedParser} can consume and parse
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
28 the message incrementally, and only returns the root object when you close the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
29 parser\footnote{As of email package version 3.0, introduced in
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
30 Python 2.4, the classic \class{Parser} was re-implemented in terms of the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
31 \class{FeedParser}, so the semantics and results are identical between the two
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
32 parsers.}.
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
33
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
34 Note that the parser can be extended in limited ways, and of course
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
35 you can implement your own parser completely from scratch. There is
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
36 no magical connection between the \module{email} package's bundled
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
37 parser and the \class{Message} class, so your custom parser can create
22005
52aa3e3e577f Merge trunk.
Greg Ward <gward@python.net>
parents: 20459
diff changeset
38 message object trees any way it finds necessary.
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
39
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
40 \subsubsection{FeedParser API}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
41
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
42 \versionadded{2.4}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
43
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
44 The \class{FeedParser}, imported from the \module{email.feedparser} module,
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
45 provides an API that is conducive to incremental parsing of email messages,
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
46 such as would be necessary when reading the text of an email message from a
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
47 source that can block (e.g. a socket). The
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
48 \class{FeedParser} can of course be used to parse an email message fully
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
49 contained in a string or a file, but the classic \class{Parser} API may be
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
50 more convenient for such use cases. The semantics and results of the two
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
51 parser APIs are identical.
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
52
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
53 The \class{FeedParser}'s API is simple; you create an instance, feed it a
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
54 bunch of text until there's no more to feed it, then close the parser to
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
55 retrieve the root message object. The \class{FeedParser} is extremely
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
56 accurate when parsing standards-compliant messages, and it does a very good
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
57 job of parsing non-compliant messages, providing information about how a
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
58 message was deemed broken. It will populate a message object's \var{defects}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
59 attribute with a list of any problems it found in a message. See the
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
60 \refmodule{email.errors} module for the list of defects that it can find.
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
61
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
62 Here is the API for the \class{FeedParser}:
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
63
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
64 \begin{classdesc}{FeedParser}{\optional{_factory}}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
65 Create a \class{FeedParser} instance. Optional \var{_factory} is a
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
66 no-argument callable that will be called whenever a new message object is
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
67 needed. It defaults to the \class{email.message.Message} class.
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
68 \end{classdesc}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
69
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
70 \begin{methoddesc}[FeedParser]{feed}{data}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
71 Feed the \class{FeedParser} some more data. \var{data} should be a
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
72 string containing one or more lines. The lines can be partial and the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
73 \class{FeedParser} will stitch such partial lines together properly. The
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
74 lines in the string can have any of the common three line endings, carriage
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
75 return, newline, or carriage return and newline (they can even be mixed).
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
76 \end{methoddesc}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
77
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
78 \begin{methoddesc}[FeedParser]{close}{}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
79 Closing a \class{FeedParser} completes the parsing of all previously fed data,
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
80 and returns the root message object. It is undefined what happens if you feed
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
81 more data to a closed \class{FeedParser}.
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
82 \end{methoddesc}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
83
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
84 \subsubsection{Parser class API}
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
85
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
86 The \class{Parser} class, imported from the \module{email.parser} module,
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
87 provides an API that can be used to parse a message when the complete contents
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
88 of the message are available in a string or file. The
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
89 \module{email.parser} module also provides a second class, called
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
90 \class{HeaderParser} which can be used if you're only interested in
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
91 the headers of the message. \class{HeaderParser} can be much faster in
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
92 these situations, since it does not attempt to parse the message body,
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
93 instead setting the payload to the raw body as a string.
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
94 \class{HeaderParser} has the same API as the \class{Parser} class.
20374
94983942c94b Describe the HeaderParser class.
Barry Warsaw <barry@python.org>
parents: 20121
diff changeset
95
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
96 \begin{classdesc}{Parser}{\optional{_class}}
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
97 The constructor for the \class{Parser} class takes an optional
20459
c68d1855daa9 Fix a few usage and style-guide conformance issues.
Fred Drake <fdrake@acm.org>
parents: 20374
diff changeset
98 argument \var{_class}. This must be a callable factory (such as a
c68d1855daa9 Fix a few usage and style-guide conformance issues.
Fred Drake <fdrake@acm.org>
parents: 20374
diff changeset
99 function or a class), and it is used whenever a sub-message object
c68d1855daa9 Fix a few usage and style-guide conformance issues.
Fred Drake <fdrake@acm.org>
parents: 20374
diff changeset
100 needs to be created. It defaults to \class{Message} (see
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
101 \refmodule{email.message}). The factory will be called without
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
102 arguments.
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
103
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
104 The optional \var{strict} flag is ignored. \deprecated{2.4}{Because the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
105 \class{Parser} class is a backward compatible API wrapper around the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
106 new-in-Python 2.4 \class{FeedParser}, \emph{all} parsing is effectively
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
107 non-strict. You should simply stop passing a \var{strict} flag to the
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
108 \class{Parser} constructor.}
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
109
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
110 \versionchanged[The \var{strict} flag was added]{2.2.2}
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
111 \versionchanged[The \var{strict} flag was deprecated]{2.4}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
112 \end{classdesc}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
113
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
114 The other public \class{Parser} methods are:
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
115
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
116 \begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
117 Read all the data from the file-like object \var{fp}, parse the
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
118 resulting text, and return the root message object. \var{fp} must
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
119 support both the \method{readline()} and the \method{read()} methods
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
120 on file-like objects.
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
121
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
122 The text contained in \var{fp} must be formatted as a block of \rfc{2822}
25513
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
123 style headers and header continuation lines, optionally preceded by a
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
124 envelope header. The header block is terminated either by the
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
125 end of the data or by a blank line. Following the header block is the
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
126 body of the message (which may contain MIME-encoded subparts).
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
127
25513
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
128 Optional \var{headersonly} is as with the \method{parse()} method.
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
129
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
130 \versionchanged[The \var{headersonly} flag was added]{2.2.2}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
131 \end{methoddesc}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
132
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
133 \begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
134 Similar to the \method{parse()} method, except it takes a string
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
135 object instead of a file-like object. Calling this method on a string
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
136 is exactly equivalent to wrapping \var{text} in a \class{StringIO}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
137 instance first and calling \method{parse()}.
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
138
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
139 Optional \var{headersonly} is a flag specifying whether to stop
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
140 parsing after reading the headers or not. The default is \code{False},
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
141 meaning it parses the entire contents of the file.
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
142
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
143 \versionchanged[The \var{headersonly} flag was added]{2.2.2}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
144 \end{methoddesc}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
145
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
146 Since creating a message object structure from a string or a file
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
147 object is such a common task, two functions are provided as a
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
148 convenience. They are available in the top-level \module{email}
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
149 package namespace.
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
150
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
151 \begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}}
25513
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
152 Return a message object structure from a string. This is exactly
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
153 equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
154 \var{strict} are interpreted as with the \class{Parser} class constructor.
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
155
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
156 \versionchanged[The \var{strict} flag was added]{2.2.2}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
157 \end{funcdesc}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
158
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
159 \begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}}
25513
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
160 Return a message object structure tree from an open file object. This
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
161 is exactly equivalent to \code{Parser().parse(fp)}. Optional
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
162 \var{_class} and \var{strict} are interpreted as with the
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
163 \class{Parser} class constructor.
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
164
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
165 \versionchanged[The \var{strict} flag was added]{2.2.2}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
166 \end{funcdesc}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
167
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
168 Here's an example of how you might use this at an interactive Python
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
169 prompt:
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
170
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
171 \begin{verbatim}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
172 >>> import email
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
173 >>> msg = email.message_from_string(myString)
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
174 \end{verbatim}
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
175
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
176 \subsubsection{Additional notes}
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
177
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
178 Here are some notes on the parsing semantics:
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
179
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
180 \begin{itemize}
20121
f822b356c3d9 Updates do email package documentation for markup, style, and
Barry Warsaw <barry@python.org>
parents: 20098
diff changeset
181 \item Most non-\mimetype{multipart} type messages are parsed as a single
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
182 message object with a string payload. These objects will return
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
183 \code{False} for \method{is_multipart()}. Their
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
184 \method{get_payload()} method will return a string object.
25521
Barry Warsaw <barry@python.org>
parents: 25513
diff changeset
185
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
186 \item All \mimetype{multipart} type messages will be parsed as a
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
187 container message object with a list of sub-message objects for
25513
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
188 their payload. The outer container message will return
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
189 \code{True} for \method{is_multipart()} and their
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
190 \method{get_payload()} method will return the list of
bd04e2bd437f Proofread and spell checked, all except the Examples section (which
Barry Warsaw <barry@python.org>
parents: 25511
diff changeset
191 \class{Message} subparts.
25521
Barry Warsaw <barry@python.org>
parents: 25513
diff changeset
192
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
193 \item Most messages with a content type of \mimetype{message/*}
31583
0b13761820b0 fix typo in reference to RFC 3464 DSN MIME type
Fred Drake <fdrake@acm.org>
parents: 25521
diff changeset
194 (e.g. \mimetype{message/delivery-status} and
25511
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
195 \mimetype{message/rfc822}) will also be parsed as container
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
196 object containing a list payload of length 1. Their
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
197 \method{is_multipart()} method will return \code{True}. The
d1b6b2ca9d9b Vast update to email version 2. This could surely use proofreading.
Barry Warsaw <barry@python.org>
parents: 22005
diff changeset
198 single element in the list payload will be a sub-message object.
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
199
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
200 \item Some non-standards compliant messages may not be internally consistent
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
201 about their \mimetype{multipart}-edness. Such messages may have a
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
202 \mailheader{Content-Type} header of type \mimetype{multipart}, but their
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
203 \method{is_multipart()} method may return \code{False}. If such
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
204 messages were parsed with the \class{FeedParser}, they will have an
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
205 instance of the \class{MultipartInvariantViolationDefect} class in their
37078
3f90a93ff5d0 Merge email package 4.0 from the sandbox, including documentation, test cases,
Barry Warsaw <barry@python.org>
parents: 33651
diff changeset
206 \var{defects} attribute list. See \refmodule{email.errors} for
33651
946612f64a83 Big email 3.0 API changes, with updated unit tests and documentation.
Barry Warsaw <barry@python.org>
parents: 31583
diff changeset
207 details.
20098
56bdd90c9fd6 The email package documentation, currently organized the way I think
Barry Warsaw <barry@python.org>
parents:
diff changeset
208 \end{itemize}