ref: 88ccea37f65b87312292b2b1a107c39927c6a2c3
dir: /sys/src/cmd/python/Doc/lib/emailmimebase.tex/
\declaremodule{standard}{email.mime} \declaremodule{standard}{email.mime.base} \declaremodule{standard}{email.mime.nonmultipart} \declaremodule{standard}{email.mime.multipart} \declaremodule{standard}{email.mime.audio} \declaremodule{standard}{email.mime.image} \declaremodule{standard}{email.mime.message} \declaremodule{standard}{email.mime.text} Ordinarily, you get a message object structure by passing a file or some text to a parser, which parses the text and returns the root message object. However you can also build a complete message structure from scratch, or even individual \class{Message} objects by hand. In fact, you can also take an existing structure and add new \class{Message} objects, move them around, etc. This makes a very convenient interface for slicing-and-dicing MIME messages. You can create a new object structure by creating \class{Message} instances, adding attachments and all the appropriate headers manually. For MIME messages though, the \module{email} package provides some convenient subclasses to make things easier. Here are the classes: \begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params} Module: \module{email.mime.base} This is the base class for all the MIME-specific subclasses of \class{Message}. Ordinarily you won't create instances specifically of \class{MIMEBase}, although you could. \class{MIMEBase} is provided primarily as a convenient base class for more specific MIME-aware subclasses. \var{_maintype} is the \mailheader{Content-Type} major type (e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the \mailheader{Content-Type} minor type (e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter key/value dictionary and is passed directly to \method{Message.add_header()}. The \class{MIMEBase} class always adds a \mailheader{Content-Type} header (based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a \mailheader{MIME-Version} header (always set to \code{1.0}). \end{classdesc} \begin{classdesc}{MIMENonMultipart}{} Module: \module{email.mime.nonmultipart} A subclass of \class{MIMEBase}, this is an intermediate base class for MIME messages that are not \mimetype{multipart}. The primary purpose of this class is to prevent the use of the \method{attach()} method, which only makes sense for \mimetype{multipart} messages. If \method{attach()} is called, a \exception{MultipartConversionError} exception is raised. \versionadded{2.2.2} \end{classdesc} \begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{, boundary\optional{, _subparts\optional{, _params}}}}} Module: \module{email.mime.multipart} A subclass of \class{MIMEBase}, this is an intermediate base class for MIME messages that are \mimetype{multipart}. Optional \var{_subtype} defaults to \mimetype{mixed}, but can be used to specify the subtype of the message. A \mailheader{Content-Type} header of \mimetype{multipart/}\var{_subtype} will be added to the message object. A \mailheader{MIME-Version} header will also be added. Optional \var{boundary} is the multipart boundary string. When \code{None} (the default), the boundary is calculated when needed. \var{_subparts} is a sequence of initial subparts for the payload. It must be possible to convert this sequence to a list. You can always attach new subparts to the message by using the \method{Message.attach()} method. Additional parameters for the \mailheader{Content-Type} header are taken from the keyword arguments, or passed into the \var{_params} argument, which is a keyword dictionary. \versionadded{2.2.2} \end{classdesc} \begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{, _encoder\optional{, **_params}}}} Module: \module{email.mime.application} A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is used to represent MIME message objects of major type \mimetype{application}. \var{_data} is a string containing the raw byte data. Optional \var{_subtype} specifies the MIME subtype and defaults to \mimetype{octet-stream}. Optional \var{_encoder} is a callable (i.e. function) which will perform the actual encoding of the data for transport. This callable takes one argument, which is the \class{MIMEApplication} instance. It should use \method{get_payload()} and \method{set_payload()} to change the payload to encoded form. It should also add any \mailheader{Content-Transfer-Encoding} or other headers to the message object as necessary. The default encoding is base64. See the \refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the base class constructor. \versionadded{2.5} \end{classdesc} \begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{, _encoder\optional{, **_params}}}} Module: \module{email.mime.audio} A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class is used to create MIME message objects of major type \mimetype{audio}. \var{_audiodata} is a string containing the raw audio data. If this data can be decoded by the standard Python module \refmodule{sndhdr}, then the subtype will be automatically included in the \mailheader{Content-Type} header. Otherwise you can explicitly specify the audio subtype via the \var{_subtype} parameter. If the minor type could not be guessed and \var{_subtype} was not given, then \exception{TypeError} is raised. Optional \var{_encoder} is a callable (i.e. function) which will perform the actual encoding of the audio data for transport. This callable takes one argument, which is the \class{MIMEAudio} instance. It should use \method{get_payload()} and \method{set_payload()} to change the payload to encoded form. It should also add any \mailheader{Content-Transfer-Encoding} or other headers to the message object as necessary. The default encoding is base64. See the \refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the base class constructor. \end{classdesc} \begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{, _encoder\optional{, **_params}}}} Module: \module{email.mime.image} A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is used to create MIME message objects of major type \mimetype{image}. \var{_imagedata} is a string containing the raw image data. If this data can be decoded by the standard Python module \refmodule{imghdr}, then the subtype will be automatically included in the \mailheader{Content-Type} header. Otherwise you can explicitly specify the image subtype via the \var{_subtype} parameter. If the minor type could not be guessed and \var{_subtype} was not given, then \exception{TypeError} is raised. Optional \var{_encoder} is a callable (i.e. function) which will perform the actual encoding of the image data for transport. This callable takes one argument, which is the \class{MIMEImage} instance. It should use \method{get_payload()} and \method{set_payload()} to change the payload to encoded form. It should also add any \mailheader{Content-Transfer-Encoding} or other headers to the message object as necessary. The default encoding is base64. See the \refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the \class{MIMEBase} constructor. \end{classdesc} \begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}} Module: \module{email.mime.message} A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class is used to create MIME objects of main type \mimetype{message}. \var{_msg} is used as the payload, and must be an instance of class \class{Message} (or a subclass thereof), otherwise a \exception{TypeError} is raised. Optional \var{_subtype} sets the subtype of the message; it defaults to \mimetype{rfc822}. \end{classdesc} \begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}} Module: \module{email.mime.text} A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is used to create MIME objects of major type \mimetype{text}. \var{_text} is the string for the payload. \var{_subtype} is the minor type and defaults to \mimetype{plain}. \var{_charset} is the character set of the text and is passed as a parameter to the \class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No guessing or encoding is performed on the text data. \versionchanged[The previously deprecated \var{_encoding} argument has been removed. Encoding happens implicitly based on the \var{_charset} argument]{2.4} \end{classdesc}