1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
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. Each of these classes
should be imported from a module with the same name as the class, from
within the \module{email} package. E.g.:
\begin{verbatim}
import email.MIMEImage.MIMEImage
\end{verbatim}
or
\begin{verbatim}
from email.MIMEText import MIMEText
\end{verbatim}
Here are the classes:
\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
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}{}
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}}}}}
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}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
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}}}}
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}}
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}}}
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}
|
