Doc/lib/emailmimebase.tex

   1 Ordinarily, you get a message object structure by passing a file or
   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.
   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
 102 object as necessary.  The default encoding is base64.  See the
 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
 127 object as necessary.  The default encoding is base64.  See the
 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
 145 \begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{,
 146     _charset\optional{, _encoder}}}}
 147
 148 A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
 149 used to create MIME objects of major type \mimetype{text}.
 150 \var{_text} is the string for the payload.  \var{_subtype} is the
 151 minor type and defaults to \mimetype{plain}.  \var{_charset} is the
 152 character set of the text and is passed as a parameter to the
 153 \class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}.  No
 154 guessing or encoding is performed on the text data, but a newline is
 155 appended to \var{_text} if it doesn't already end with a newline.
 156
 157 \deprecated{2.2.2}{The \var{_encoding} argument has been deprecated.
 158 Encoding now happens implicitly based on the \var{_charset} argument.}
 159 \end{classdesc}