sys/src/cmd/python/Doc/lib/emailmimebase.tex

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