Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 1 | % Copyright (C) 2001-2006 Python Software Foundation |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 2 | % Author: barry@python.org (Barry Warsaw) |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 3 | |
Fred Drake | a6a885b | 2001-09-26 16:52:18 +0000 | [diff] [blame] | 4 | \section{\module{email} --- |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 5 | An email and MIME handling package} |
| 6 | |
| 7 | \declaremodule{standard}{email} |
| 8 | \modulesynopsis{Package supporting the parsing, manipulating, and |
| 9 | generating email messages, including MIME documents.} |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 10 | \moduleauthor{Barry A. Warsaw}{barry@python.org} |
| 11 | \sectionauthor{Barry A. Warsaw}{barry@python.org} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 12 | |
| 13 | \versionadded{2.2} |
| 14 | |
| 15 | The \module{email} package is a library for managing email messages, |
| 16 | including MIME and other \rfc{2822}-based message documents. It |
| 17 | subsumes most of the functionality in several older standard modules |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 18 | such as \refmodule{rfc822}, \refmodule{mimetools}, |
| 19 | \refmodule{multifile}, and other non-standard packages such as |
Barry Warsaw | 5e17d20 | 2001-11-16 22:16:04 +0000 | [diff] [blame] | 20 | \module{mimecntl}. It is specifically \emph{not} designed to do any |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 21 | sending of email messages to SMTP (\rfc{2821}), NNTP, or other servers; those |
| 22 | are functions of modules such as \refmodule{smtplib} and \refmodule{nntplib}. |
| 23 | The \module{email} package attempts to be as RFC-compliant as possible, |
| 24 | supporting in addition to \rfc{2822}, such MIME-related RFCs as |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 25 | \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 26 | |
| 27 | The primary distinguishing feature of the \module{email} package is |
| 28 | that it splits the parsing and generating of email messages from the |
| 29 | internal \emph{object model} representation of email. Applications |
| 30 | using the \module{email} package deal primarily with objects; you can |
| 31 | add sub-objects to messages, remove sub-objects from messages, |
| 32 | completely re-arrange the contents, etc. There is a separate parser |
| 33 | and a separate generator which handles the transformation from flat |
Andrew M. Kuchling | 43dc1fc | 2001-11-05 01:55:03 +0000 | [diff] [blame] | 34 | text to the object model, and then back to flat text again. There |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 35 | are also handy subclasses for some common MIME object types, and a few |
| 36 | miscellaneous utilities that help with such common tasks as extracting |
| 37 | and parsing message field values, creating RFC-compliant dates, etc. |
| 38 | |
| 39 | The following sections describe the functionality of the |
| 40 | \module{email} package. The ordering follows a progression that |
| 41 | should be common in applications: an email message is read as flat |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 42 | text from a file or other source, the text is parsed to produce the |
| 43 | object structure of the email message, this structure is manipulated, |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 44 | and finally, the object tree is rendered back into flat text. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 45 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 46 | It is perfectly feasible to create the object structure out of whole |
| 47 | cloth --- i.e. completely from scratch. From there, a similar |
| 48 | progression can be taken as above. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 49 | |
| 50 | Also included are detailed specifications of all the classes and |
| 51 | modules that the \module{email} package provides, the exception |
| 52 | classes you might encounter while using the \module{email} package, |
| 53 | some auxiliary utilities, and a few examples. For users of the older |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 54 | \module{mimelib} package, or previous versions of the \module{email} |
| 55 | package, a section on differences and porting is provided. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 56 | |
Barry Warsaw | 5e17d20 | 2001-11-16 22:16:04 +0000 | [diff] [blame] | 57 | \begin{seealso} |
| 58 | \seemodule{smtplib}{SMTP protocol client} |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 59 | \seemodule{nntplib}{NNTP protocol client} |
Barry Warsaw | 5e17d20 | 2001-11-16 22:16:04 +0000 | [diff] [blame] | 60 | \end{seealso} |
| 61 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 62 | \subsection{Representing an email message} |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 63 | \input{emailmessage} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 64 | |
| 65 | \subsection{Parsing email messages} |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 66 | \input{emailparser} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 67 | |
| 68 | \subsection{Generating MIME documents} |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 69 | \input{emailgenerator} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 70 | |
| 71 | \subsection{Creating email and MIME objects from scratch} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 72 | \input{emailmimebase} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 73 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 74 | \subsection{Internationalized headers} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 75 | \input{emailheaders} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 76 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 77 | \subsection{Representing character sets} |
| 78 | \input{emailcharsets} |
| 79 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 80 | \subsection{Encoders} |
| 81 | \input{emailencoders} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 82 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 83 | \subsection{Exception and Defect classes} |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 84 | \input{emailexc} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 85 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 86 | \subsection{Miscellaneous utilities} |
| 87 | \input{emailutil} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 88 | |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 89 | \subsection{Iterators} |
| 90 | \input{emailiter} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 91 | |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 92 | \subsection{Package History\label{email-pkg-history}} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 93 | |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 94 | This table describes the release history of the email package, corresponding |
| 95 | to the version of Python that the package was released with. For purposes of |
| 96 | this document, when you see a note about change or added versions, these refer |
| 97 | to the Python version the change was made it, \emph{not} the email package |
| 98 | version. This table also describes the Python compatibility of each version |
| 99 | of the package. |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 100 | |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 101 | \begin{tableiii}{l|l|l}{constant}{email version}{distributed with}{compatible with} |
| 102 | \lineiii{1.x}{Python 2.2.0 to Python 2.2.1}{\emph{no longer supported}} |
| 103 | \lineiii{2.5}{Python 2.2.2+ and Python 2.3}{Python 2.1 to 2.5} |
| 104 | \lineiii{3.0}{Python 2.4}{Python 2.3 to 2.5} |
| 105 | \lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5} |
| 106 | \end{tableiii} |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 107 | |
Barry Warsaw | b110bad | 2006-07-21 14:51:07 +0000 | [diff] [blame^] | 108 | Here are the major differences between \module{email} version 4 and version 3: |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 109 | |
| 110 | \begin{itemize} |
| 111 | \item All modules have been renamed according to \pep{8} standards. For |
| 112 | example, the version 3 module \module{email.Message} was renamed to |
| 113 | \module{email.message} in version 4. |
| 114 | |
| 115 | \item A new subpackage \module{email.mime} was added and all the version 3 |
| 116 | \module{email.MIME*} modules were renamed and situated into the |
| 117 | \module{email.mime} subpackage. For example, the version 3 module |
| 118 | \module{email.MIMEText} was renamed to \module{email.mime.text}. |
| 119 | |
| 120 | \emph{Note that the version 3 names will continue to work until Python |
| 121 | 2.6}. |
| 122 | |
| 123 | \item The \module{email.mime.application} module was added, which contains the |
| 124 | \class{MIMEApplication} class. |
| 125 | |
| 126 | \item Methods that were deprecated in version 3 have been removed. These |
| 127 | include \method{Generator.__call__()}, \method{Message.get_type()}, |
| 128 | \method{Message.get_main_type()}, \method{Message.get_subtype()}. |
Barry Warsaw | b110bad | 2006-07-21 14:51:07 +0000 | [diff] [blame^] | 129 | |
| 130 | \item Fixes have been added for \rfc{2231} support which can change some of |
| 131 | the return types for \function{Message.get_param()} and friends. Under |
| 132 | some circumstances, values which used to return a 3-tuple now return |
| 133 | simple strings (specifically, if all extended parameter segments were |
| 134 | unencoded, there is no language and charset designation expected, so the |
| 135 | return type is now a simple string). Also, \%-decoding used to be done |
| 136 | for both encoded and unencoded segments; this decoding is now done only |
| 137 | for encoded segments. |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 138 | \end{itemize} |
| 139 | |
| 140 | Here are the major differences between \module{email} version 3 and version 2: |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 141 | |
| 142 | \begin{itemize} |
| 143 | \item The \class{FeedParser} class was introduced, and the \class{Parser} |
| 144 | class was implemented in terms of the \class{FeedParser}. All parsing |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 145 | therefore is non-strict, and parsing will make a best effort never to |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 146 | raise an exception. Problems found while parsing messages are stored in |
| 147 | the message's \var{defect} attribute. |
| 148 | |
| 149 | \item All aspects of the API which raised \exception{DeprecationWarning}s in |
| 150 | version 2 have been removed. These include the \var{_encoder} argument |
| 151 | to the \class{MIMEText} constructor, the \method{Message.add_payload()} |
| 152 | method, the \function{Utils.dump_address_pair()} function, and the |
| 153 | functions \function{Utils.decode()} and \function{Utils.encode()}. |
| 154 | |
| 155 | \item New \exception{DeprecationWarning}s have been added to: |
| 156 | \method{Generator.__call__()}, \method{Message.get_type()}, |
| 157 | \method{Message.get_main_type()}, \method{Message.get_subtype()}, and |
| 158 | the \var{strict} argument to the \class{Parser} class. These are |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 159 | expected to be removed in future versions. |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 160 | |
| 161 | \item Support for Pythons earlier than 2.3 has been removed. |
| 162 | \end{itemize} |
| 163 | |
| 164 | Here are the differences between \module{email} version 2 and version 1: |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 165 | |
| 166 | \begin{itemize} |
| 167 | \item The \module{email.Header} and \module{email.Charset} modules |
| 168 | have been added. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 169 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 170 | \item The pickle format for \class{Message} instances has changed. |
| 171 | Since this was never (and still isn't) formally defined, this |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 172 | isn't considered a backward incompatibility. However if your |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 173 | application pickles and unpickles \class{Message} instances, be |
| 174 | aware that in \module{email} version 2, \class{Message} |
| 175 | instances now have private variables \var{_charset} and |
| 176 | \var{_default_type}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 177 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 178 | \item Several methods in the \class{Message} class have been |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 179 | deprecated, or their signatures changed. Also, many new methods |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 180 | have been added. See the documentation for the \class{Message} |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 181 | class for details. The changes should be completely backward |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 182 | compatible. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 183 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 184 | \item The object structure has changed in the face of |
| 185 | \mimetype{message/rfc822} content types. In \module{email} |
| 186 | version 1, such a type would be represented by a scalar payload, |
| 187 | i.e. the container message's \method{is_multipart()} returned |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 188 | false, \method{get_payload()} was not a list object, but a single |
| 189 | \class{Message} instance. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 190 | |
| 191 | This structure was inconsistent with the rest of the package, so |
| 192 | the object representation for \mimetype{message/rfc822} content |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 193 | types was changed. In \module{email} version 2, the container |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 194 | \emph{does} return \code{True} from \method{is_multipart()}, and |
| 195 | \method{get_payload()} returns a list containing a single |
| 196 | \class{Message} item. |
| 197 | |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 198 | Note that this is one place that backward compatibility could |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 199 | not be completely maintained. However, if you're already |
| 200 | testing the return type of \method{get_payload()}, you should be |
| 201 | fine. You just need to make sure your code doesn't do a |
| 202 | \method{set_payload()} with a \class{Message} instance on a |
| 203 | container with a content type of \mimetype{message/rfc822}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 204 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 205 | \item The \class{Parser} constructor's \var{strict} argument was |
| 206 | added, and its \method{parse()} and \method{parsestr()} methods |
| 207 | grew a \var{headersonly} argument. The \var{strict} flag was |
| 208 | also added to functions \function{email.message_from_file()} |
| 209 | and \function{email.message_from_string()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 210 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 211 | \item \method{Generator.__call__()} is deprecated; use |
| 212 | \method{Generator.flatten()} instead. The \class{Generator} |
| 213 | class has also grown the \method{clone()} method. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 214 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 215 | \item The \class{DecodedGenerator} class in the |
| 216 | \module{email.Generator} module was added. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 217 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 218 | \item The intermediate base classes \class{MIMENonMultipart} and |
| 219 | \class{MIMEMultipart} have been added, and interposed in the |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 220 | class hierarchy for most of the other MIME-related derived |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 221 | classes. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 222 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 223 | \item The \var{_encoder} argument to the \class{MIMEText} constructor |
| 224 | has been deprecated. Encoding now happens implicitly based |
| 225 | on the \var{_charset} argument. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 226 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 227 | \item The following functions in the \module{email.Utils} module have |
| 228 | been deprecated: \function{dump_address_pairs()}, |
| 229 | \function{decode()}, and \function{encode()}. The following |
| 230 | functions have been added to the module: |
| 231 | \function{make_msgid()}, \function{decode_rfc2231()}, |
| 232 | \function{encode_rfc2231()}, and \function{decode_params()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 233 | |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 234 | \item The non-public function \function{email.Iterators._structure()} |
| 235 | was added. |
| 236 | \end{itemize} |
| 237 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 238 | \subsection{Differences from \module{mimelib}} |
| 239 | |
| 240 | The \module{email} package was originally prototyped as a separate |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 241 | library called |
| 242 | \ulink{\module{mimelib}}{http://mimelib.sf.net/}. |
| 243 | Changes have been made so that |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 244 | method names are more consistent, and some methods or modules have |
| 245 | either been added or removed. The semantics of some of the methods |
| 246 | have also changed. For the most part, any functionality available in |
Fred Drake | 90e6878 | 2001-09-27 20:09:39 +0000 | [diff] [blame] | 247 | \module{mimelib} is still available in the \refmodule{email} package, |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 248 | albeit often in a different way. Backward compatibility between |
| 249 | the \module{mimelib} package and the \module{email} package was not a |
| 250 | priority. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 251 | |
| 252 | Here is a brief description of the differences between the |
Fred Drake | 90e6878 | 2001-09-27 20:09:39 +0000 | [diff] [blame] | 253 | \module{mimelib} and the \refmodule{email} packages, along with hints on |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 254 | how to port your applications. |
| 255 | |
| 256 | Of course, the most visible difference between the two packages is |
Fred Drake | 90e6878 | 2001-09-27 20:09:39 +0000 | [diff] [blame] | 257 | that the package name has been changed to \refmodule{email}. In |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 258 | addition, the top-level package has the following differences: |
| 259 | |
| 260 | \begin{itemize} |
| 261 | \item \function{messageFromString()} has been renamed to |
| 262 | \function{message_from_string()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 263 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 264 | \item \function{messageFromFile()} has been renamed to |
| 265 | \function{message_from_file()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 266 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 267 | \end{itemize} |
| 268 | |
| 269 | The \class{Message} class has the following differences: |
| 270 | |
| 271 | \begin{itemize} |
| 272 | \item The method \method{asString()} was renamed to \method{as_string()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 273 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 274 | \item The method \method{ismultipart()} was renamed to |
| 275 | \method{is_multipart()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 276 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 277 | \item The \method{get_payload()} method has grown a \var{decode} |
| 278 | optional argument. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 279 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 280 | \item The method \method{getall()} was renamed to \method{get_all()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 281 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 282 | \item The method \method{addheader()} was renamed to \method{add_header()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 283 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 284 | \item The method \method{gettype()} was renamed to \method{get_type()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 285 | |
Georg Brandl | 89f000e | 2005-06-04 10:01:15 +0000 | [diff] [blame] | 286 | \item The method \method{getmaintype()} was renamed to |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 287 | \method{get_main_type()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 288 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 289 | \item The method \method{getsubtype()} was renamed to |
| 290 | \method{get_subtype()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 291 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 292 | \item The method \method{getparams()} was renamed to |
| 293 | \method{get_params()}. |
| 294 | Also, whereas \method{getparams()} returned a list of strings, |
| 295 | \method{get_params()} returns a list of 2-tuples, effectively |
Barry Warsaw | c5f8fe3 | 2001-09-26 22:21:52 +0000 | [diff] [blame] | 296 | the key/value pairs of the parameters, split on the \character{=} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 297 | sign. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 298 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 299 | \item The method \method{getparam()} was renamed to \method{get_param()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 300 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 301 | \item The method \method{getcharsets()} was renamed to |
| 302 | \method{get_charsets()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 303 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 304 | \item The method \method{getfilename()} was renamed to |
| 305 | \method{get_filename()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 306 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 307 | \item The method \method{getboundary()} was renamed to |
| 308 | \method{get_boundary()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 309 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 310 | \item The method \method{setboundary()} was renamed to |
| 311 | \method{set_boundary()}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 312 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 313 | \item The method \method{getdecodedpayload()} was removed. To get |
| 314 | similar functionality, pass the value 1 to the \var{decode} flag |
| 315 | of the {get_payload()} method. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 316 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 317 | \item The method \method{getpayloadastext()} was removed. Similar |
| 318 | functionality |
| 319 | is supported by the \class{DecodedGenerator} class in the |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 320 | \refmodule{email.generator} module. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 321 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 322 | \item The method \method{getbodyastext()} was removed. You can get |
| 323 | similar functionality by creating an iterator with |
| 324 | \function{typed_subpart_iterator()} in the |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 325 | \refmodule{email.iterators} module. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 326 | \end{itemize} |
| 327 | |
| 328 | The \class{Parser} class has no differences in its public interface. |
| 329 | It does have some additional smarts to recognize |
Fred Drake | a6a885b | 2001-09-26 16:52:18 +0000 | [diff] [blame] | 330 | \mimetype{message/delivery-status} type messages, which it represents as |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 331 | a \class{Message} instance containing separate \class{Message} |
| 332 | subparts for each header block in the delivery status |
| 333 | notification\footnote{Delivery Status Notifications (DSN) are defined |
Fred Drake | 90e6878 | 2001-09-27 20:09:39 +0000 | [diff] [blame] | 334 | in \rfc{1894}.}. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 335 | |
| 336 | The \class{Generator} class has no differences in its public |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 337 | interface. There is a new class in the \refmodule{email.generator} |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 338 | module though, called \class{DecodedGenerator} which provides most of |
| 339 | the functionality previously available in the |
| 340 | \method{Message.getpayloadastext()} method. |
| 341 | |
| 342 | The following modules and classes have been changed: |
| 343 | |
| 344 | \begin{itemize} |
| 345 | \item The \class{MIMEBase} class constructor arguments \var{_major} |
| 346 | and \var{_minor} have changed to \var{_maintype} and |
| 347 | \var{_subtype} respectively. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 348 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 349 | \item The \code{Image} class/module has been renamed to |
| 350 | \code{MIMEImage}. The \var{_minor} argument has been renamed to |
| 351 | \var{_subtype}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 352 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 353 | \item The \code{Text} class/module has been renamed to |
| 354 | \code{MIMEText}. The \var{_minor} argument has been renamed to |
| 355 | \var{_subtype}. |
Barry Warsaw | dd868d3 | 2002-10-01 15:29:09 +0000 | [diff] [blame] | 356 | |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 357 | \item The \code{MessageRFC822} class/module has been renamed to |
| 358 | \code{MIMEMessage}. Note that an earlier version of |
| 359 | \module{mimelib} called this class/module \code{RFC822}, but |
| 360 | that clashed with the Python standard library module |
| 361 | \refmodule{rfc822} on some case-insensitive file systems. |
| 362 | |
| 363 | Also, the \class{MIMEMessage} class now represents any kind of |
Fred Drake | a6a885b | 2001-09-26 16:52:18 +0000 | [diff] [blame] | 364 | MIME message with main type \mimetype{message}. It takes an |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 365 | optional argument \var{_subtype} which is used to set the MIME |
Fred Drake | a6a885b | 2001-09-26 16:52:18 +0000 | [diff] [blame] | 366 | subtype. \var{_subtype} defaults to \mimetype{rfc822}. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 367 | \end{itemize} |
| 368 | |
| 369 | \module{mimelib} provided some utility functions in its |
| 370 | \module{address} and \module{date} modules. All of these functions |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 371 | have been moved to the \refmodule{email.utils} module. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 372 | |
| 373 | The \code{MsgReader} class/module has been removed. Its functionality |
| 374 | is most closely supported in the \function{body_line_iterator()} |
Barry Warsaw | 40ef006 | 2006-03-18 15:41:53 +0000 | [diff] [blame] | 375 | function in the \refmodule{email.iterators} module. |
Barry Warsaw | 5e63463 | 2001-09-26 05:23:47 +0000 | [diff] [blame] | 376 | |
| 377 | \subsection{Examples} |
| 378 | |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 379 | Here are a few examples of how to use the \module{email} package to |
| 380 | read, write, and send simple email messages, as well as more complex |
| 381 | MIME messages. |
| 382 | |
| 383 | First, let's see how to create and send a simple text message: |
| 384 | |
Fred Drake | fcc31b4 | 2002-10-01 14:17:10 +0000 | [diff] [blame] | 385 | \verbatiminput{email-simple.py} |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 386 | |
| 387 | Here's an example of how to send a MIME message containing a bunch of |
Barry Warsaw | ea66abc | 2002-10-01 04:48:06 +0000 | [diff] [blame] | 388 | family pictures that may be residing in a directory: |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 389 | |
Fred Drake | fcc31b4 | 2002-10-01 14:17:10 +0000 | [diff] [blame] | 390 | \verbatiminput{email-mime.py} |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 391 | |
Fred Drake | 7934bc2 | 2003-01-29 05:10:27 +0000 | [diff] [blame] | 392 | Here's an example of how to send the entire contents of a directory as |
| 393 | an email message: |
| 394 | \footnote{Thanks to Matthew Dixon Cowles for the original inspiration |
| 395 | and examples.} |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 396 | |
Fred Drake | fcc31b4 | 2002-10-01 14:17:10 +0000 | [diff] [blame] | 397 | \verbatiminput{email-dir.py} |
Barry Warsaw | 2bb077f | 2001-11-05 17:50:53 +0000 | [diff] [blame] | 398 | |
| 399 | And finally, here's an example of how to unpack a MIME message like |
| 400 | the one above, into a directory of files: |
| 401 | |
Fred Drake | fcc31b4 | 2002-10-01 14:17:10 +0000 | [diff] [blame] | 402 | \verbatiminput{email-unpack.py} |