Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(2)

Delta Between Two Patch Sets: Doc/library/email.mime.rst

Issue 18761: Fix internal doc references for the email package (Closed)
Left Patch Set: Created 6 years, 5 months ago
Right Patch Set: Created 6 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « Doc/library/email.message.rst ('k') | Doc/library/email.parser.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`email.mime`: Creating email and MIME objects from scratch 1 :mod:`email.mime`: Creating email and MIME objects from scratch
2 --------------------------------------------------------------- 2 ---------------------------------------------------------------
3 3
4 .. module:: email.mime 4 .. module:: email.mime
5 :synopsis: Build MIME messages. 5 :synopsis: Build MIME messages.
6 6
7 7
8 Ordinarily, you get a message object structure by passing a file or some text to 8 Ordinarily, you get a message object structure by passing a file or some text to
9 a parser, which parses the text and returns the root message object. However 9 a parser, which parses the text and returns the root message object. However
10 you can also build a complete message structure from scratch, or even individual 10 you can also build a complete message structure from scratch, or even individual
(...skipping 17 matching lines...) Expand all
28 28
29 This is the base class for all the MIME-specific subclasses of 29 This is the base class for all the MIME-specific subclasses of
30 :class:`~email.message.Message`. Ordinarily you won't create instances 30 :class:`~email.message.Message`. Ordinarily you won't create instances
31 specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase` 31 specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase`
32 is provided primarily as a convenient base class for more specific 32 is provided primarily as a convenient base class for more specific
33 MIME-aware subclasses. 33 MIME-aware subclasses.
34 34
35 *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`tex t` 35 *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`tex t`
36 or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor 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 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 <ema il.message.Message.add_header>`. 38 key/value dictionary and is passed directly to :meth:`Message.add_header
39 <email.message.Message.add_header>`.
39 40
40 The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header 41 The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
41 (based on *_maintype*, *_subtype*, and *_params*), and a 42 (based on *_maintype*, *_subtype*, and *_params*), and a
42 :mailheader:`MIME-Version` header (always set to ``1.0``). 43 :mailheader:`MIME-Version` header (always set to ``1.0``).
43 44
44 45
45 .. currentmodule:: email.mime.nonmultipart 46 .. currentmodule:: email.mime.nonmultipart
46 47
47 .. class:: MIMENonMultipart() 48 .. class:: MIMENonMultipart()
48 49
49 Module: :mod:`email.mime.nonmultipart` 50 Module: :mod:`email.mime.nonmultipart`
50 51
51 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate bas e 52 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate bas e
52 class for MIME messages that are not :mimetype:`multipart`. The primary 53 class for MIME messages that are not :mimetype:`multipart`. The primary
53 purpose of this class is to prevent the use of the :meth:`~email.message.Mess age.attach` method, 54 purpose of this class is to prevent the use of the
54 which only makes sense for :mimetype:`multipart` messages. If :meth:`~email. message.Message.attach` 55 :meth:`~email.message.Message.attach` method, which only makes sense for
56 :mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
55 is called, a :exc:`~email.errors.MultipartConversionError` exception is raise d. 57 is called, a :exc:`~email.errors.MultipartConversionError` exception is raise d.
56 58
57 59
58 .. currentmodule:: email.mime.multipart 60 .. currentmodule:: email.mime.multipart
59 61
60 .. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_par ams) 62 .. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_par ams)
61 63
62 Module: :mod:`email.mime.multipart` 64 Module: :mod:`email.mime.multipart`
63 65
64 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate bas e 66 A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate bas e
65 class for MIME messages that are :mimetype:`multipart`. Optional *_subtype* 67 class for MIME messages that are :mimetype:`multipart`. Optional *_subtype*
66 defaults to :mimetype:`mixed`, but can be used to specify the subtype of the 68 defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
67 message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtyp e` 69 message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtyp e`
68 will be added to the message object. A :mailheader:`MIME-Version` header wil l 70 will be added to the message object. A :mailheader:`MIME-Version` header wil l
69 also be added. 71 also be added.
70 72
71 Optional *boundary* is the multipart boundary string. When ``None`` (the 73 Optional *boundary* is the multipart boundary string. When ``None`` (the
72 default), the boundary is calculated when needed (for example, when the 74 default), the boundary is calculated when needed (for example, when the
73 message is serialized). 75 message is serialized).
74 76
75 *_subparts* is a sequence of initial subparts for the payload. It must be 77 *_subparts* is a sequence of initial subparts for the payload. It must be
76 possible to convert this sequence to a list. You can always attach new subpa rts 78 possible to convert this sequence to a list. You can always attach new subpa rts
77 to the message by using the :meth:`Message.attach <email.message.Message.atta ch>` method. 79 to the message by using the :meth:`Message.attach
80 <email.message.Message.attach>` method.
78 81
79 Additional parameters for the :mailheader:`Content-Type` header are taken fro m 82 Additional parameters for the :mailheader:`Content-Type` header are taken fro m
80 the keyword arguments, or passed into the *_params* argument, which is a keyw ord 83 the keyword arguments, or passed into the *_params* argument, which is a keyw ord
81 dictionary. 84 dictionary.
82 85
83 86
84 .. currentmodule:: email.mime.application 87 .. currentmodule:: email.mime.application
85 88
86 .. class:: MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encode rs.encode_base64, **_params) 89 .. class:: MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encode rs.encode_base64, **_params)
87 90
88 Module: :mod:`email.mime.application` 91 Module: :mod:`email.mime.application`
89 92
90 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the 93 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
91 :class:`MIMEApplication` class is used to represent MIME message objects of 94 :class:`MIMEApplication` class is used to represent MIME message objects of
92 major type :mimetype:`application`. *_data* is a string containing the raw 95 major type :mimetype:`application`. *_data* is a string containing the raw
93 byte data. Optional *_subtype* specifies the MIME subtype and defaults to 96 byte data. Optional *_subtype* specifies the MIME subtype and defaults to
94 :mimetype:`octet-stream`. 97 :mimetype:`octet-stream`.
95 98
96 Optional *_encoder* is a callable (i.e. function) which will perform the actu al 99 Optional *_encoder* is a callable (i.e. function) which will perform the actu al
97 encoding of the data for transport. This callable takes one argument, which is 100 encoding of the data for transport. This callable takes one argument, which is
98 the :class:`MIMEApplication` instance. It should use :meth:`~email.message.Me ssage.get_payload` and 101 the :class:`MIMEApplication` instance. It should use
99 :meth:`~email.message.Message.set_payload` to change the payload to encoded f orm. It should also add 102 :meth:`~email.message.Message.get_payload` and
103 :meth:`~email.message.Message.set_payload` to change the payload to encoded
104 form. It should also add
100 any :mailheader:`Content-Transfer-Encoding` or other headers to the message 105 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
101 object as necessary. The default encoding is base64. See the 106 object as necessary. The default encoding is base64. See the
102 :mod:`email.encoders` module for a list of the built-in encoders. 107 :mod:`email.encoders` module for a list of the built-in encoders.
103 108
104 *_params* are passed straight through to the base class constructor. 109 *_params* are passed straight through to the base class constructor.
105 110
106 111
107 .. currentmodule:: email.mime.audio 112 .. currentmodule:: email.mime.audio
108 113
109 .. class:: MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_b ase64, **_params) 114 .. class:: MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_b ase64, **_params)
110 115
111 Module: :mod:`email.mime.audio` 116 Module: :mod:`email.mime.audio`
112 117
113 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the 118 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
114 :class:`MIMEAudio` class is used to create MIME message objects of major type 119 :class:`MIMEAudio` class is used to create MIME message objects of major type
115 :mimetype:`audio`. *_audiodata* is a string containing the raw audio data. I f 120 :mimetype:`audio`. *_audiodata* is a string containing the raw audio data. I f
116 this data can be decoded by the standard Python module :mod:`sndhdr`, then th e 121 this data can be decoded by the standard Python module :mod:`sndhdr`, then th e
117 subtype will be automatically included in the :mailheader:`Content-Type` head er. 122 subtype will be automatically included in the :mailheader:`Content-Type` head er.
118 Otherwise you can explicitly specify the audio subtype via the *_subtype* 123 Otherwise you can explicitly specify the audio subtype via the *_subtype*
119 argument. If the minor type could not be guessed and *_subtype* was not give n, 124 argument. If the minor type could not be guessed and *_subtype* was not give n,
120 then :exc:`TypeError` is raised. 125 then :exc:`TypeError` is raised.
121 126
122 Optional *_encoder* is a callable (i.e. function) which will perform the actu al 127 Optional *_encoder* is a callable (i.e. function) which will perform the actu al
123 encoding of the audio data for transport. This callable takes one argument, 128 encoding of the audio data for transport. This callable takes one argument,
124 which is the :class:`MIMEAudio` instance. It should use :meth:`~email.message .Message.get_payload` and 129 which is the :class:`MIMEAudio` instance. It should use
125 :meth:`~email.message.Message.set_payload` to change the payload to encoded f orm. It should also add 130 :meth:`~email.message.Message.get_payload` and
131 :meth:`~email.message.Message.set_payload` to change the payload to encoded
132 form. It should also add
126 any :mailheader:`Content-Transfer-Encoding` or other headers to the message 133 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
127 object as necessary. The default encoding is base64. See the 134 object as necessary. The default encoding is base64. See the
128 :mod:`email.encoders` module for a list of the built-in encoders. 135 :mod:`email.encoders` module for a list of the built-in encoders.
129 136
130 *_params* are passed straight through to the base class constructor. 137 *_params* are passed straight through to the base class constructor.
131 138
132 139
133 .. currentmodule:: email.mime.image 140 .. currentmodule:: email.mime.image
134 141
135 .. class:: MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_b ase64, **_params) 142 .. class:: MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_b ase64, **_params)
136 143
137 Module: :mod:`email.mime.image` 144 Module: :mod:`email.mime.image`
138 145
139 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the 146 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
140 :class:`MIMEImage` class is used to create MIME message objects of major type 147 :class:`MIMEImage` class is used to create MIME message objects of major type
141 :mimetype:`image`. *_imagedata* is a string containing the raw image data. I f 148 :mimetype:`image`. *_imagedata* is a string containing the raw image data. I f
142 this data can be decoded by the standard Python module :mod:`imghdr`, then th e 149 this data can be decoded by the standard Python module :mod:`imghdr`, then th e
143 subtype will be automatically included in the :mailheader:`Content-Type` head er. 150 subtype will be automatically included in the :mailheader:`Content-Type` head er.
144 Otherwise you can explicitly specify the image subtype via the *_subtype* 151 Otherwise you can explicitly specify the image subtype via the *_subtype*
145 argument. If the minor type could not be guessed and *_subtype* was not give n, 152 argument. If the minor type could not be guessed and *_subtype* was not give n,
146 then :exc:`TypeError` is raised. 153 then :exc:`TypeError` is raised.
147 154
148 Optional *_encoder* is a callable (i.e. function) which will perform the actu al 155 Optional *_encoder* is a callable (i.e. function) which will perform the actu al
149 encoding of the image data for transport. This callable takes one argument, 156 encoding of the image data for transport. This callable takes one argument,
150 which is the :class:`MIMEImage` instance. It should use :meth:`~email.message .Message.get_payload` and 157 which is the :class:`MIMEImage` instance. It should use
151 :meth:`~email.message.Message.set_payload` to change the payload to encoded f orm. It should also add 158 :meth:`~email.message.Message.get_payload` and
159 :meth:`~email.message.Message.set_payload` to change the payload to encoded
160 form. It should also add
152 any :mailheader:`Content-Transfer-Encoding` or other headers to the message 161 any :mailheader:`Content-Transfer-Encoding` or other headers to the message
153 object as necessary. The default encoding is base64. See the 162 object as necessary. The default encoding is base64. See the
154 :mod:`email.encoders` module for a list of the built-in encoders. 163 :mod:`email.encoders` module for a list of the built-in encoders.
155 164
156 *_params* are passed straight through to the :class:`~email.mime.base.MIMEBas e` 165 *_params* are passed straight through to the :class:`~email.mime.base.MIMEBas e`
157 constructor. 166 constructor.
158 167
159 168
160 .. currentmodule:: email.mime.message 169 .. currentmodule:: email.mime.message
161 170
(...skipping 28 matching lines...) Expand all
190 199
191 Unless the *_charset* argument is explicitly set to ``None``, the 200 Unless the *_charset* argument is explicitly set to ``None``, the
192 MIMEText object created will have both a :mailheader:`Content-Type` header 201 MIMEText object created will have both a :mailheader:`Content-Type` header
193 with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding` 202 with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding`
194 header. This means that a subsequent ``set_payload`` call will not result 203 header. This means that a subsequent ``set_payload`` call will not result
195 in an encoded payload, even if a charset is passed in the ``set_payload`` 204 in an encoded payload, even if a charset is passed in the ``set_payload``
196 command. You can "reset" this behavior by deleting the 205 command. You can "reset" this behavior by deleting the
197 ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call 206 ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
198 will automatically encode the new payload (and add a new 207 will automatically encode the new payload (and add a new
199 :mailheader:`Content-Transfer-Encoding` header). 208 :mailheader:`Content-Transfer-Encoding` header).
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+