rest25/library/email.parser.rst => rest262/library/email.parser.rst
n1+:mod:`email`: Parsing email messages
2+------------------------------------
3+ 
1.. module:: email.parser
2   :synopsis: Parse flat text email messages to produce a message object structure.
3
4
5Message object structures can be created in one of two ways: they can be created
6from whole cloth by instantiating :class:`Message` objects and stringing them
7together via :meth:`attach` and :meth:`set_payload` calls, or they can be
8created by parsing a flat text representation of the email message.
43that can block (e.g. a socket).  The :class:`FeedParser` can of course be used
44to parse an email message fully contained in a string or a file, but the classic
45:class:`Parser` API may be more convenient for such use cases.  The semantics
46and results of the two parser APIs are identical.
47
48The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
49of text until there's no more to feed it, then close the parser to retrieve the
50root message object.  The :class:`FeedParser` is extremely accurate when parsing
n51-standards-compliant messages, and it does a very good job of parsing non-
n54+standards-compliant messages, and it does a very good job of parsing
52-compliant messages, providing information about how a message was deemed broken.
55+non-compliant messages, providing information about how a message was deemed
53-It will populate a message object's *defects* attribute with a list of any
56+broken.  It will populate a message object's *defects* attribute with a list of
54-problems it found in a message.  See the :mod:`email.errors` module for the list
57+any problems it found in a message.  See the :mod:`email.errors` module for the
55-of defects that it can find.
58+list of defects that it can find.
56
57Here is the API for the :class:`FeedParser`:
58
59
60.. class:: FeedParser([_factory])
61
62   Create a :class:`FeedParser` instance.  Optional *_factory* is a no-argument
63   callable that will be called whenever a new message object is needed.  It
64   defaults to the :class:`email.message.Message` class.
65
66
n67-.. method:: FeedParser.feed(data)
n70+   .. method:: feed(data)
68
n69-   Feed the :class:`FeedParser` some more data.  *data* should be a string
n72+      Feed the :class:`FeedParser` some more data.  *data* should be a string
70-   containing one or more lines.  The lines can be partial and the
73+      containing one or more lines.  The lines can be partial and the
71-   :class:`FeedParser` will stitch such partial lines together properly.  The lines
74+      :class:`FeedParser` will stitch such partial lines together properly.  The
72-   in the string can have any of the common three line endings, carriage return,
75+      lines in the string can have any of the common three line endings,
73-   newline, or carriage return and newline (they can even be mixed).
76+      carriage return, newline, or carriage return and newline (they can even be
77+      mixed).
74
75
n76-.. method:: FeedParser.close()
n80+   .. method:: close()
77
n78-   Closing a :class:`FeedParser` completes the parsing of all previously fed data,
n82+      Closing a :class:`FeedParser` completes the parsing of all previously fed
79-   and returns the root message object.  It is undefined what happens if you feed
83+      data, and returns the root message object.  It is undefined what happens
80-   more data to a closed :class:`FeedParser`.
84+      if you feed more data to a closed :class:`FeedParser`.
81
82
83Parser class API
84^^^^^^^^^^^^^^^^
85
86The :class:`Parser` class, imported from the :mod:`email.parser` module,
87provides an API that can be used to parse a message when the complete contents
88of the message are available in a string or file.  The :mod:`email.parser`
100   *_class*.  This must be a callable factory (such as a function or a class), and
101   it is used whenever a sub-message object needs to be created.  It defaults to
102   :class:`Message` (see :mod:`email.message`).  The factory will be called without
103   arguments.
104
105   The optional *strict* flag is ignored.
106
107   .. deprecated:: 2.4
n108-      Because the :class:`Parser` class is a backward compatible API wrapper around
n112+      Because the :class:`Parser` class is a backward compatible API wrapper
109-      the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is effectively non-
113+      around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
110-      strict.  You should simply stop passing a *strict* flag to the :class:`Parser`
114+      effectively non-strict.  You should simply stop passing a *strict* flag to
111-      constructor.
115+      the :class:`Parser` constructor.
112
113   .. versionchanged:: 2.2.2
114      The *strict* flag was added.
115
116   .. versionchanged:: 2.4
117      The *strict* flag was deprecated.
118
n119-The other public :class:`Parser` methods are:
n123+   The other public :class:`Parser` methods are:
120
121
n122-.. method:: Parser.parse(fp[, headersonly])
n126+   .. method:: parse(fp[, headersonly])
123
n124-   Read all the data from the file-like object *fp*, parse the resulting text, and
n128+      Read all the data from the file-like object *fp*, parse the resulting
125-   return the root message object.  *fp* must support both the :meth:`readline` and
129+      text, and return the root message object.  *fp* must support both the
126-   the :meth:`read` methods on file-like objects.
130+      :meth:`readline` and the :meth:`read` methods on file-like objects.
127
n128-   The text contained in *fp* must be formatted as a block of :rfc:`2822` style
n132+      The text contained in *fp* must be formatted as a block of :rfc:`2822`
129-   headers and header continuation lines, optionally preceded by a envelope header.
133+      style headers and header continuation lines, optionally preceded by a
130-   The header block is terminated either by the end of the data or by a blank line.
134+      envelope header.  The header block is terminated either by the end of the
131-   Following the header block is the body of the message (which may contain MIME-
135+      data or by a blank line.  Following the header block is the body of the
132-   encoded subparts).
136+      message (which may contain MIME-encoded subparts).
133
n134-   Optional *headersonly* is as with the :meth:`parse` method.
n138+      Optional *headersonly* is as with the :meth:`parse` method.
135
n136-   .. versionchanged:: 2.2.2
n140+      .. versionchanged:: 2.2.2
137-      The *headersonly* flag was added.
141+         The *headersonly* flag was added.
138
139
n140-.. method:: Parser.parsestr(text[, headersonly])
n144+   .. method:: parsestr(text[, headersonly])
141
n142-   Similar to the :meth:`parse` method, except it takes a string object instead of
n146+      Similar to the :meth:`parse` method, except it takes a string object
143-   a file-like object.  Calling this method on a string is exactly equivalent to
147+      instead of a file-like object.  Calling this method on a string is exactly
144-   wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`.
148+      equivalent to wrapping *text* in a :class:`StringIO` instance first and
149+      calling :meth:`parse`.
145
n146-   Optional *headersonly* is a flag specifying whether to stop parsing after
n151+      Optional *headersonly* is a flag specifying whether to stop parsing after
147-   reading the headers or not.  The default is ``False``, meaning it parses the
152+      reading the headers or not.  The default is ``False``, meaning it parses
148-   entire contents of the file.
153+      the entire contents of the file.
149
n150-   .. versionchanged:: 2.2.2
n155+      .. versionchanged:: 2.2.2
151-      The *headersonly* flag was added.
156+         The *headersonly* flag was added.
152
153Since creating a message object structure from a string or a file object is such
154a common task, two functions are provided as a convenience.  They are available
155in the top-level :mod:`email` package namespace.
156
t162+.. currentmodule:: email
157
158.. function:: message_from_string(s[, _class[, strict]])
159
160   Return a message object structure from a string.  This is exactly equivalent to
161   ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
162   with the :class:`Parser` class constructor.
163
164   .. versionchanged:: 2.2.2
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op