PageRenderTime 494ms CodeModel.GetById 202ms app.highlight 137ms RepoModel.GetById 145ms app.codeStats 0ms

/Doc/library/email.mime.rst

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