| that can block (e.g. a socket). The :class:`FeedParser` can of course be used |
| to parse an email message fully contained in a string or a file, but the classic |
| :class:`Parser` API may be more convenient for such use cases. The semantics |
| and results of the two parser APIs are identical. |
| |
| The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch |
| of text until there's no more to feed it, then close the parser to retrieve the |
| root message object. The :class:`FeedParser` is extremely accurate when parsing |
n | standards-compliant messages, and it does a very good job of parsing non- |
n | standards-compliant messages, and it does a very good job of parsing |
| compliant messages, providing information about how a message was deemed broken. |
| non-compliant messages, providing information about how a message was deemed |
| It will populate a message object's *defects* attribute with a list of any |
| broken. It will populate a message object's *defects* attribute with a list of |
| problems it found in a message. See the :mod:`email.errors` module for the list |
| any problems it found in a message. See the :mod:`email.errors` module for the |
| of defects that it can find. |
| list of defects that it can find. |
| |
| Here is the API for the :class:`FeedParser`: |
| |
| |
| .. class:: FeedParser([_factory]) |
| |
| Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument |
| callable that will be called whenever a new message object is needed. It |
| defaults to the :class:`email.message.Message` class. |
| |
| |
n | .. method:: FeedParser.feed(data) |
n | .. method:: feed(data) |
| |
n | Feed the :class:`FeedParser` some more data. *data* should be a string |
n | Feed the :class:`FeedParser` some more data. *data* should be a string |
| containing one or more lines. The lines can be partial and the |
| containing one or more lines. The lines can be partial and the |
| :class:`FeedParser` will stitch such partial lines together properly. The lines |
| :class:`FeedParser` will stitch such partial lines together properly. The |
| in the string can have any of the common three line endings, carriage return, |
| lines in the string can have any of the common three line endings, |
| newline, or carriage return and newline (they can even be mixed). |
| carriage return, newline, or carriage return and newline (they can even be |
| mixed). |
| |
| |
n | .. method:: FeedParser.close() |
n | .. method:: close() |
| |
n | Closing a :class:`FeedParser` completes the parsing of all previously fed data, |
n | Closing a :class:`FeedParser` completes the parsing of all previously fed |
| and returns the root message object. It is undefined what happens if you feed |
| data, and returns the root message object. It is undefined what happens |
| more data to a closed :class:`FeedParser`. |
| if you feed more data to a closed :class:`FeedParser`. |
| |
| |
| Parser class API |
| ^^^^^^^^^^^^^^^^ |
| |
| The :class:`Parser` class, imported from the :mod:`email.parser` module, |
| provides an API that can be used to parse a message when the complete contents |
| of the message are available in a string or file. The :mod:`email.parser` |
| *_class*. This must be a callable factory (such as a function or a class), and |
| it is used whenever a sub-message object needs to be created. It defaults to |
| :class:`Message` (see :mod:`email.message`). The factory will be called without |
| arguments. |
| |
| The optional *strict* flag is ignored. |
| |
| .. deprecated:: 2.4 |
n | Because the :class:`Parser` class is a backward compatible API wrapper around |
n | Because the :class:`Parser` class is a backward compatible API wrapper |
| the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is effectively non- |
| around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is |
| strict. You should simply stop passing a *strict* flag to the :class:`Parser` |
| effectively non-strict. You should simply stop passing a *strict* flag to |
| constructor. |
| the :class:`Parser` constructor. |
| |
| .. versionchanged:: 2.2.2 |
| The *strict* flag was added. |
| |
| .. versionchanged:: 2.4 |
| The *strict* flag was deprecated. |
| |
n | The other public :class:`Parser` methods are: |
n | The other public :class:`Parser` methods are: |
| |
| |
n | .. method:: Parser.parse(fp[, headersonly]) |
n | .. method:: parse(fp[, headersonly]) |
| |
n | Read all the data from the file-like object *fp*, parse the resulting text, and |
n | Read all the data from the file-like object *fp*, parse the resulting |
| return the root message object. *fp* must support both the :meth:`readline` and |
| text, and return the root message object. *fp* must support both the |
| the :meth:`read` methods on file-like objects. |
| :meth:`readline` and the :meth:`read` methods on file-like objects. |
| |
n | The text contained in *fp* must be formatted as a block of :rfc:`2822` style |
n | The text contained in *fp* must be formatted as a block of :rfc:`2822` |
| headers and header continuation lines, optionally preceded by a envelope header. |
| style headers and header continuation lines, optionally preceded by a |
| The header block is terminated either by the end of the data or by a blank line. |
| envelope header. The header block is terminated either by the end of the |
| Following the header block is the body of the message (which may contain MIME- |
| data or by a blank line. Following the header block is the body of the |
| encoded subparts). |
| message (which may contain MIME-encoded subparts). |
| |
n | Optional *headersonly* is as with the :meth:`parse` method. |
n | Optional *headersonly* is as with the :meth:`parse` method. |
| |
n | .. versionchanged:: 2.2.2 |
n | .. versionchanged:: 2.2.2 |
| The *headersonly* flag was added. |
| The *headersonly* flag was added. |
| |
| |
n | .. method:: Parser.parsestr(text[, headersonly]) |
n | .. method:: parsestr(text[, headersonly]) |
| |
n | Similar to the :meth:`parse` method, except it takes a string object instead of |
n | Similar to the :meth:`parse` method, except it takes a string object |
| a file-like object. Calling this method on a string is exactly equivalent to |
| instead of a file-like object. Calling this method on a string is exactly |
| wrapping *text* in a :class:`StringIO` instance first and calling :meth:`parse`. |
| equivalent to wrapping *text* in a :class:`StringIO` instance first and |
| calling :meth:`parse`. |
| |
n | Optional *headersonly* is a flag specifying whether to stop parsing after |
n | Optional *headersonly* is a flag specifying whether to stop parsing after |
| reading the headers or not. The default is ``False``, meaning it parses the |
| reading the headers or not. The default is ``False``, meaning it parses |
| entire contents of the file. |
| the entire contents of the file. |
| |
n | .. versionchanged:: 2.2.2 |
n | .. versionchanged:: 2.2.2 |
| The *headersonly* flag was added. |
| The *headersonly* flag was added. |
| |
| Since creating a message object structure from a string or a file object is such |
| a common task, two functions are provided as a convenience. They are available |
| in the top-level :mod:`email` package namespace. |
| |
t | .. currentmodule:: email |
| |
| .. function:: message_from_string(s[, _class[, strict]]) |
| |
| Return a message object structure from a string. This is exactly equivalent to |
| ``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as |
| with the :class:`Parser` class constructor. |
| |
| .. versionchanged:: 2.2.2 |