rest25/library/email.mime.rst => rest262/library/email.mime.rst
n1+:mod:`email`: Creating email and MIME objects from scratch
2+----------------------------------------------------------
3+ 
1-.. module:: email.mime.text
4+.. module:: email.mime
5+   :synopsis: Build MIME messages.
2
3
4Ordinarily, you get a message object structure by passing a file or some text to
5a parser, which parses the text and returns the root message object.  However
6you can also build a complete message structure from scratch, or even individual
7:class:`Message` objects by hand.  In fact, you can also take an existing
8structure and add new :class:`Message` objects, move them around, etc.  This
9makes a very convenient interface for slicing-and-dicing MIME messages.
10
11You can create a new object structure by creating :class:`Message` instances,
12adding attachments and all the appropriate headers manually.  For MIME messages
13though, the :mod:`email` package provides some convenient subclasses to make
14things easier.
15
16Here are the classes:
17
n22+.. currentmodule:: email.mime.base
18
19.. class:: MIMEBase(_maintype, _subtype, **_params)
20
21   Module: :mod:`email.mime.base`
22
23   This is the base class for all the MIME-specific subclasses of :class:`Message`.
24   Ordinarily you won't create instances specifically of :class:`MIMEBase`,
25   although you could.  :class:`MIMEBase` is provided primarily as a convenient
30   type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
31   key/value dictionary and is passed directly to :meth:`Message.add_header`.
32
33   The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
34   (based on *_maintype*, *_subtype*, and *_params*), and a
35   :mailheader:`MIME-Version` header (always set to ``1.0``).
36
37
n43+.. currentmodule:: email.mime.nonmultipart
44+ 
38.. class:: MIMENonMultipart()
39
40   Module: :mod:`email.mime.nonmultipart`
41
42   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
43   messages that are not :mimetype:`multipart`.  The primary purpose of this class
44   is to prevent the use of the :meth:`attach` method, which only makes sense for
45   :mimetype:`multipart` messages.  If :meth:`attach` is called, a
46   :exc:`MultipartConversionError` exception is raised.
47
48   .. versionadded:: 2.2.2
49
50
n58+.. currentmodule:: email.mime.multipart
59+ 
51-.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])
60+.. class:: MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])
52
53   Module: :mod:`email.mime.multipart`
54
55   A subclass of :class:`MIMEBase`, this is an intermediate base class for MIME
56   messages that are :mimetype:`multipart`.  Optional *_subtype* defaults to
57   :mimetype:`mixed`, but can be used to specify the subtype of the message.  A
n58-   :mailheader:`Content-Type` header of :mimetype:`multipart/`*_subtype* will be
n67+   :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` will be
59   added to the message object.  A :mailheader:`MIME-Version` header will also be
60   added.
61
62   Optional *boundary* is the multipart boundary string.  When ``None`` (the
63   default), the boundary is calculated when needed.
64
65   *_subparts* is a sequence of initial subparts for the payload.  It must be
66   possible to convert this sequence to a list.  You can always attach new subparts
67   to the message by using the :meth:`Message.attach` method.
68
69   Additional parameters for the :mailheader:`Content-Type` header are taken from
70   the keyword arguments, or passed into the *_params* argument, which is a keyword
71   dictionary.
72
73   .. versionadded:: 2.2.2
74
n84+ 
85+.. currentmodule:: email.mime.application
75
76.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
77
78   Module: :mod:`email.mime.application`
79
80   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEApplication` class is
81   used to represent MIME message objects of major type :mimetype:`application`.
82   *_data* is a string containing the raw byte data.  Optional *_subtype* specifies
89   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
90   object as necessary.  The default encoding is base64.  See the
91   :mod:`email.encoders` module for a list of the built-in encoders.
92
93   *_params* are passed straight through to the base class constructor.
94
95   .. versionadded:: 2.5
96
n108+ 
109+.. currentmodule:: email.mime.audio
97
98.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
99
100   Module: :mod:`email.mime.audio`
101
102   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEAudio` class is used to
103   create MIME message objects of major type :mimetype:`audio`. *_audiodata* is a
104   string containing the raw audio data.  If this data can be decoded by the
113   :meth:`set_payload` to change the payload to encoded form.  It should also add
114   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
115   object as necessary.  The default encoding is base64.  See the
116   :mod:`email.encoders` module for a list of the built-in encoders.
117
118   *_params* are passed straight through to the base class constructor.
119
120
n134+.. currentmodule:: email.mime.image
135+ 
121.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
122
123   Module: :mod:`email.mime.image`
124
125   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEImage` class is used to
126   create MIME message objects of major type :mimetype:`image`. *_imagedata* is a
127   string containing the raw image data.  If this data can be decoded by the
128   standard Python module :mod:`imghdr`, then the subtype will be automatically
136   :meth:`set_payload` to change the payload to encoded form.  It should also add
137   any :mailheader:`Content-Transfer-Encoding` or other headers to the message
138   object as necessary.  The default encoding is base64.  See the
139   :mod:`email.encoders` module for a list of the built-in encoders.
140
141   *_params* are passed straight through to the :class:`MIMEBase` constructor.
142
143
n159+.. currentmodule:: email.mime.message
160+ 
144.. class:: MIMEMessage(_msg[, _subtype])
145
146   Module: :mod:`email.mime.message`
147
148   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEMessage` class is used
149   to create MIME objects of main type :mimetype:`message`. *_msg* is used as the
150   payload, and must be an instance of class :class:`Message` (or a subclass
151   thereof), otherwise a :exc:`TypeError` is raised.
152
153   Optional *_subtype* sets the subtype of the message; it defaults to
154   :mimetype:`rfc822`.
155
t173+ 
174+.. currentmodule:: email.mime.text
156
157.. class:: MIMEText(_text[, _subtype[, _charset]])
158
159   Module: :mod:`email.mime.text`
160
161   A subclass of :class:`MIMENonMultipart`, the :class:`MIMEText` class is used to
162   create MIME objects of major type :mimetype:`text`. *_text* is the string for
163   the payload.  *_subtype* is the minor type and defaults to :mimetype:`plain`.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op