Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 1 | \declaremodule{standard}{email.Parser} |
| 2 | \modulesynopsis{Parse flat text email messages to produce a message |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 3 | object structure.} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 4 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 5 | Message object structures can be created in one of two ways: they can be |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 6 | created from whole cloth by instantiating \class{Message} objects and |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 7 | stringing them together via \method{attach()} and |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 8 | \method{set_payload()} calls, or they can be created by parsing a flat text |
| 9 | representation of the email message. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 10 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 11 | The \module{email} package provides a standard parser that understands |
| 12 | most email document structures, including MIME documents. You can |
| 13 | pass the parser a string or a file object, and the parser will return |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 14 | to you the root \class{Message} instance of the object structure. For |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 15 | simple, non-MIME messages the payload of this root object will likely |
Fred Drake | ab9b238 | 2001-10-16 19:22:51 +0000 | [diff] [blame] | 16 | be a string containing the text of the message. For MIME |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 17 | messages, the root object will return \code{True} from its |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 18 | \method{is_multipart()} method, and the subparts can be accessed via |
| 19 | the \method{get_payload()} and \method{walk()} methods. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 20 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 21 | Note that the parser can be extended in limited ways, and of course |
| 22 | you can implement your own parser completely from scratch. There is |
| 23 | no magical connection between the \module{email} package's bundled |
| 24 | parser and the \class{Message} class, so your custom parser can create |
Greg Ward | f8b1f24 | 2002-02-22 21:24:32 +0000 | [diff] [blame] | 25 | message object trees any way it finds necessary. |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 26 | |
Barry Warsaw | c7f8b86 | 2001-10-11 15:45:05 +0000 | [diff] [blame] | 27 | The primary parser class is \class{Parser} which parses both the |
| 28 | headers and the payload of the message. In the case of |
| 29 | \mimetype{multipart} messages, it will recursively parse the body of |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 30 | the container message. Two modes of parsing are supported, |
| 31 | \emph{strict} parsing, which will usually reject any non-RFC compliant |
| 32 | message, and \emph{lax} parsing, which attempts to adjust for common |
| 33 | MIME formatting problems. |
| 34 | |
| 35 | The \module{email.Parser} module also provides a second class, called |
| 36 | \class{HeaderParser} which can be used if you're only interested in |
| 37 | the headers of the message. \class{HeaderParser} can be much faster in |
| 38 | these situations, since it does not attempt to parse the message body, |
| 39 | instead setting the payload to the raw body as a string. |
| 40 | \class{HeaderParser} has the same API as the \class{Parser} class. |
Barry Warsaw | c7f8b86 | 2001-10-11 15:45:05 +0000 | [diff] [blame] | 41 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 42 | \subsubsection{Parser class API} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 43 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 44 | \begin{classdesc}{Parser}{\optional{_class\optional{, strict}}} |
| 45 | The constructor for the \class{Parser} class takes an optional |
Fred Drake | ab9b238 | 2001-10-16 19:22:51 +0000 | [diff] [blame] | 46 | argument \var{_class}. This must be a callable factory (such as a |
| 47 | function or a class), and it is used whenever a sub-message object |
| 48 | needs to be created. It defaults to \class{Message} (see |
| 49 | \refmodule{email.Message}). The factory will be called without |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 50 | arguments. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 51 | |
| 52 | The optional \var{strict} flag specifies whether strict or lax parsing |
| 53 | should be performed. Normally, when things like MIME terminating |
| 54 | boundaries are missing, or when messages contain other formatting |
| 55 | problems, the \class{Parser} will raise a |
| 56 | \exception{MessageParseError}. However, when lax parsing is enabled, |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 57 | the \class{Parser} will attempt to work around such broken formatting |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 58 | to produce a usable message structure (this doesn't mean |
| 59 | \exception{MessageParseError}s are never raised; some ill-formatted |
| 60 | messages just can't be parsed). The \var{strict} flag defaults to |
| 61 | \code{False} since lax parsing usually provides the most convenient |
| 62 | behavior. |
| 63 | |
| 64 | \versionchanged[The \var{strict} flag was added]{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 65 | \end{classdesc} |
| 66 | |
| 67 | The other public \class{Parser} methods are: |
| 68 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 69 | \begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 70 | Read all the data from the file-like object \var{fp}, parse the |
| 71 | resulting text, and return the root message object. \var{fp} must |
| 72 | support both the \method{readline()} and the \method{read()} methods |
| 73 | on file-like objects. |
| 74 | |
| 75 | The text contained in \var{fp} must be formatted as a block of \rfc{2822} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 76 | style headers and header continuation lines, optionally preceded by a |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 77 | envelope header. The header block is terminated either by the |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 78 | end of the data or by a blank line. Following the header block is the |
| 79 | body of the message (which may contain MIME-encoded subparts). |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 80 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 81 | Optional \var{headersonly} is as with the \method{parse()} method. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 82 | |
| 83 | \versionchanged[The \var{headersonly} flag was added]{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 84 | \end{methoddesc} |
| 85 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 86 | \begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 87 | Similar to the \method{parse()} method, except it takes a string |
| 88 | object instead of a file-like object. Calling this method on a string |
| 89 | is exactly equivalent to wrapping \var{text} in a \class{StringIO} |
| 90 | instance first and calling \method{parse()}. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 91 | |
| 92 | Optional \var{headersonly} is a flag specifying whether to stop |
| 93 | parsing after reading the headers or not. The default is \code{False}, |
| 94 | meaning it parses the entire contents of the file. |
| 95 | |
| 96 | \versionchanged[The \var{headersonly} flag was added]{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 97 | \end{methoddesc} |
| 98 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 99 | Since creating a message object structure from a string or a file |
| 100 | object is such a common task, two functions are provided as a |
| 101 | convenience. They are available in the top-level \module{email} |
| 102 | package namespace. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 103 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 104 | \begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 105 | Return a message object structure from a string. This is exactly |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 106 | equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and |
| 107 | \var{strict} are interpreted as with the \class{Parser} class constructor. |
| 108 | |
| 109 | \versionchanged[The \var{strict} flag was added]{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 110 | \end{funcdesc} |
| 111 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 112 | \begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 113 | Return a message object structure tree from an open file object. This |
| 114 | is exactly equivalent to \code{Parser().parse(fp)}. Optional |
| 115 | \var{_class} and \var{strict} are interpreted as with the |
| 116 | \class{Parser} class constructor. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 117 | |
| 118 | \versionchanged[The \var{strict} flag was added]{2.2.2} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 119 | \end{funcdesc} |
| 120 | |
| 121 | Here's an example of how you might use this at an interactive Python |
| 122 | prompt: |
| 123 | |
| 124 | \begin{verbatim} |
| 125 | >>> import email |
| 126 | >>> msg = email.message_from_string(myString) |
| 127 | \end{verbatim} |
| 128 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 129 | \subsubsection{Additional notes} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 130 | |
| 131 | Here are some notes on the parsing semantics: |
| 132 | |
| 133 | \begin{itemize} |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 134 | \item Most non-\mimetype{multipart} type messages are parsed as a single |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 135 | message object with a string payload. These objects will return |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 136 | \code{False} for \method{is_multipart()}. Their |
| 137 | \method{get_payload()} method will return a string object. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 138 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 139 | \item All \mimetype{multipart} type messages will be parsed as a |
| 140 | container message object with a list of sub-message objects for |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 141 | their payload. The outer container message will return |
| 142 | \code{True} for \method{is_multipart()} and their |
| 143 | \method{get_payload()} method will return the list of |
| 144 | \class{Message} subparts. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 145 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 146 | \item Most messages with a content type of \mimetype{message/*} |
Fred Drake | 59e02c1 | 2004-02-24 20:58:10 +0000 | [diff] [blame] | 147 | (e.g. \mimetype{message/delivery-status} and |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 148 | \mimetype{message/rfc822}) will also be parsed as container |
| 149 | object containing a list payload of length 1. Their |
| 150 | \method{is_multipart()} method will return \code{True}. The |
| 151 | single element in the list payload will be a sub-message object. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 152 | \end{itemize} |