Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 1 | Ordinarily, you get a message object structure by passing a file or |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 2 | some text to a parser, which parses the text and returns the root |
| 3 | message object. However you can also build a complete message |
| 4 | structure from scratch, or even individual \class{Message} objects by |
| 5 | hand. In fact, you can also take an existing structure and add new |
| 6 | \class{Message} objects, move them around, etc. This makes a very |
| 7 | convenient interface for slicing-and-dicing MIME messages. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 8 | |
| 9 | You can create a new object structure by creating \class{Message} |
| 10 | instances, adding attachments and all the appropriate headers manually. |
| 11 | For MIME messages though, the \module{email} package provides some |
| 12 | convenient subclasses to make things easier. Each of these classes |
| 13 | should be imported from a module with the same name as the class, from |
| 14 | within the \module{email} package. E.g.: |
| 15 | |
| 16 | \begin{verbatim} |
| 17 | import email.MIMEImage.MIMEImage |
| 18 | \end{verbatim} |
| 19 | |
| 20 | or |
| 21 | |
| 22 | \begin{verbatim} |
| 23 | from email.MIMEText import MIMEText |
| 24 | \end{verbatim} |
| 25 | |
| 26 | Here are the classes: |
| 27 | |
| 28 | \begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params} |
| 29 | This is the base class for all the MIME-specific subclasses of |
| 30 | \class{Message}. Ordinarily you won't create instances specifically |
| 31 | of \class{MIMEBase}, although you could. \class{MIMEBase} is provided |
| 32 | primarily as a convenient base class for more specific MIME-aware |
| 33 | subclasses. |
| 34 | |
| 35 | \var{_maintype} is the \mailheader{Content-Type} major type |
| 36 | (e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the |
| 37 | \mailheader{Content-Type} minor type |
| 38 | (e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter |
| 39 | key/value dictionary and is passed directly to |
| 40 | \method{Message.add_header()}. |
| 41 | |
| 42 | The \class{MIMEBase} class always adds a \mailheader{Content-Type} header |
| 43 | (based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a |
| 44 | \mailheader{MIME-Version} header (always set to \code{1.0}). |
| 45 | \end{classdesc} |
| 46 | |
| 47 | \begin{classdesc}{MIMENonMultipart}{} |
| 48 | A subclass of \class{MIMEBase}, this is an intermediate base class for |
| 49 | MIME messages that are not \mimetype{multipart}. The primary purpose |
| 50 | of this class is to prevent the use of the \method{attach()} method, |
| 51 | which only makes sense for \mimetype{multipart} messages. If |
| 52 | \method{attach()} is called, a \exception{MultipartConversionError} |
| 53 | exception is raised. |
| 54 | |
| 55 | \versionadded{2.2.2} |
| 56 | \end{classdesc} |
| 57 | |
| 58 | \begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{, |
| 59 | boundary\optional{, _subparts\optional{, _params}}}}} |
| 60 | |
| 61 | A subclass of \class{MIMEBase}, this is an intermediate base class for |
| 62 | MIME messages that are \mimetype{multipart}. Optional \var{_subtype} |
| 63 | defaults to \mimetype{mixed}, but can be used to specify the subtype |
| 64 | of the message. A \mailheader{Content-Type} header of |
| 65 | \mimetype{multipart/}\var{_subtype} will be added to the message |
| 66 | object. A \mailheader{MIME-Version} header will also be added. |
| 67 | |
| 68 | Optional \var{boundary} is the multipart boundary string. When |
| 69 | \code{None} (the default), the boundary is calculated when needed. |
| 70 | |
| 71 | \var{_subparts} is a sequence of initial subparts for the payload. It |
| 72 | must be possible to convert this sequence to a list. You can always |
| 73 | attach new subparts to the message by using the |
| 74 | \method{Message.attach()} method. |
| 75 | |
| 76 | Additional parameters for the \mailheader{Content-Type} header are |
| 77 | taken from the keyword arguments, or passed into the \var{_params} |
| 78 | argument, which is a keyword dictionary. |
| 79 | |
| 80 | \versionadded{2.2.2} |
| 81 | \end{classdesc} |
| 82 | |
| 83 | \begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{, |
| 84 | _encoder\optional{, **_params}}}} |
| 85 | |
| 86 | A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class |
| 87 | is used to create MIME message objects of major type \mimetype{audio}. |
| 88 | \var{_audiodata} is a string containing the raw audio data. If this |
| 89 | data can be decoded by the standard Python module \refmodule{sndhdr}, |
| 90 | then the subtype will be automatically included in the |
| 91 | \mailheader{Content-Type} header. Otherwise you can explicitly specify the |
| 92 | audio subtype via the \var{_subtype} parameter. If the minor type could |
| 93 | not be guessed and \var{_subtype} was not given, then \exception{TypeError} |
| 94 | is raised. |
| 95 | |
| 96 | Optional \var{_encoder} is a callable (i.e. function) which will |
| 97 | perform the actual encoding of the audio data for transport. This |
| 98 | callable takes one argument, which is the \class{MIMEAudio} instance. |
| 99 | It should use \method{get_payload()} and \method{set_payload()} to |
| 100 | change the payload to encoded form. It should also add any |
| 101 | \mailheader{Content-Transfer-Encoding} or other headers to the message |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 102 | object as necessary. The default encoding is base64. See the |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 103 | \refmodule{email.Encoders} module for a list of the built-in encoders. |
| 104 | |
| 105 | \var{_params} are passed straight through to the base class constructor. |
| 106 | \end{classdesc} |
| 107 | |
| 108 | \begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{, |
| 109 | _encoder\optional{, **_params}}}} |
| 110 | |
| 111 | A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is |
| 112 | used to create MIME message objects of major type \mimetype{image}. |
| 113 | \var{_imagedata} is a string containing the raw image data. If this |
| 114 | data can be decoded by the standard Python module \refmodule{imghdr}, |
| 115 | then the subtype will be automatically included in the |
| 116 | \mailheader{Content-Type} header. Otherwise you can explicitly specify the |
| 117 | image subtype via the \var{_subtype} parameter. If the minor type could |
| 118 | not be guessed and \var{_subtype} was not given, then \exception{TypeError} |
| 119 | is raised. |
| 120 | |
| 121 | Optional \var{_encoder} is a callable (i.e. function) which will |
| 122 | perform the actual encoding of the image data for transport. This |
| 123 | callable takes one argument, which is the \class{MIMEImage} instance. |
| 124 | It should use \method{get_payload()} and \method{set_payload()} to |
| 125 | change the payload to encoded form. It should also add any |
| 126 | \mailheader{Content-Transfer-Encoding} or other headers to the message |
Barry Warsaw | 5db478f | 2002-10-01 04:33:16 +0000 | [diff] [blame] | 127 | object as necessary. The default encoding is base64. See the |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 128 | \refmodule{email.Encoders} module for a list of the built-in encoders. |
| 129 | |
| 130 | \var{_params} are passed straight through to the \class{MIMEBase} |
| 131 | constructor. |
| 132 | \end{classdesc} |
| 133 | |
| 134 | \begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}} |
| 135 | A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class |
| 136 | is used to create MIME objects of main type \mimetype{message}. |
| 137 | \var{_msg} is used as the payload, and must be an instance of class |
| 138 | \class{Message} (or a subclass thereof), otherwise a |
| 139 | \exception{TypeError} is raised. |
| 140 | |
| 141 | Optional \var{_subtype} sets the subtype of the message; it defaults |
| 142 | to \mimetype{rfc822}. |
| 143 | \end{classdesc} |
| 144 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 145 | \begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 146 | A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is |
| 147 | used to create MIME objects of major type \mimetype{text}. |
| 148 | \var{_text} is the string for the payload. \var{_subtype} is the |
| 149 | minor type and defaults to \mimetype{plain}. \var{_charset} is the |
| 150 | character set of the text and is passed as a parameter to the |
| 151 | \class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No |
Barry Warsaw | a996d4f | 2003-03-11 05:03:25 +0000 | [diff] [blame] | 152 | guessing or encoding is performed on the text data. |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 153 | |
Barry Warsaw | bb11386 | 2004-10-03 03:16:19 +0000 | [diff] [blame] | 154 | \versionchanged[The previously deprecated \var{_encoding} argument has |
| 155 | been removed. Encoding happens implicitly based on the \var{_charset} |
| 156 | argument]{2.4} |
Barry Warsaw | 5b9da89 | 2002-10-01 01:05:52 +0000 | [diff] [blame] | 157 | \end{classdesc} |