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

Side by Side Diff: Doc/library/email.rst

Issue 18761: Fix internal doc references for the email package (Closed)
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:
View unified diff | Download patch
« no previous file with comments | « Doc/library/email.policy.rst ('k') | Doc/library/email.util.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`email` --- An email and MIME handling package 1 :mod:`email` --- An email and MIME handling package
2 =================================================== 2 ===================================================
3 3
4 .. module:: email 4 .. module:: email
5 :synopsis: Package supporting the parsing, manipulating, and generating 5 :synopsis: Package supporting the parsing, manipulating, and generating
6 email messages, including MIME documents. 6 email messages, including MIME documents.
7 .. moduleauthor:: Barry A. Warsaw <barry@python.org> 7 .. moduleauthor:: Barry A. Warsaw <barry@python.org>
8 .. sectionauthor:: Barry A. Warsaw <barry@python.org> 8 .. sectionauthor:: Barry A. Warsaw <barry@python.org>
9 .. Copyright (C) 2001-2010 Python Software Foundation 9 .. Copyright (C) 2001-2010 Python Software Foundation
10 10
(...skipping 129 matching lines...) Expand 10 before | Expand all | Expand 10 after
140 version 4. 140 version 4.
141 141
142 * A new subpackage :mod:`email.mime` was added and all the version 3 142 * A new subpackage :mod:`email.mime` was added and all the version 3
143 :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mim e` 143 :mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mim e`
144 subpackage. For example, the version 3 module :mod:`email.MIMEText` was renam ed 144 subpackage. For example, the version 3 module :mod:`email.MIMEText` was renam ed
145 to :mod:`email.mime.text`. 145 to :mod:`email.mime.text`.
146 146
147 *Note that the version 3 names will continue to work until Python 2.6*. 147 *Note that the version 3 names will continue to work until Python 2.6*.
148 148
149 * The :mod:`email.mime.application` module was added, which contains the 149 * The :mod:`email.mime.application` module was added, which contains the
150 :class:`MIMEApplication` class. 150 :class:`~email.mime.application.MIMEApplication` class.
151 151
152 * Methods that were deprecated in version 3 have been removed. These include 152 * Methods that were deprecated in version 3 have been removed. These include
153 :meth:`Generator.__call__`, :meth:`Message.get_type`, 153 :meth:`Generator.__call__`, :meth:`Message.get_type`,
154 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`. 154 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
155 155
156 * Fixes have been added for :rfc:`2231` support which can change some of the 156 * Fixes have been added for :rfc:`2231` support which can change some of the
157 return types for :func:`Message.get_param` and friends. Under some 157 return types for :func:`Message.get_param <email.message.Message.get_param>`
158 and friends. Under some
158 circumstances, values which used to return a 3-tuple now return simple strings 159 circumstances, values which used to return a 3-tuple now return simple strings
159 (specifically, if all extended parameter segments were unencoded, there is no 160 (specifically, if all extended parameter segments were unencoded, there is no
160 language and charset designation expected, so the return type is now a simple 161 language and charset designation expected, so the return type is now a simple
161 string). Also, %-decoding used to be done for both encoded and unencoded 162 string). Also, %-decoding used to be done for both encoded and unencoded
162 segments; this decoding is now done only for encoded segments. 163 segments; this decoding is now done only for encoded segments.
163 164
164 Here are the major differences between :mod:`email` version 3 and version 2: 165 Here are the major differences between :mod:`email` version 3 and version 2:
165 166
166 * The :class:`FeedParser` class was introduced, and the :class:`Parser` class 167 * The :class:`~email.parser.FeedParser` class was introduced, and the
167 was implemented in terms of the :class:`FeedParser`. All parsing therefore is 168 :class:`~email.parser.Parser` class was implemented in terms of the
169 :class:`~email.parser.FeedParser`. All parsing therefore is
168 non-strict, and parsing will make a best effort never to raise an exception. 170 non-strict, and parsing will make a best effort never to raise an exception.
169 Problems found while parsing messages are stored in the message's *defect* 171 Problems found while parsing messages are stored in the message's *defect*
170 attribute. 172 attribute.
171 173
172 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 174 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
173 have been removed. These include the *_encoder* argument to the 175 have been removed. These include the *_encoder* argument to the
174 :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the 176 :class:`~email.mime.text.MIMEText` constructor, the
175 :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decod e` 177 :meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
176 and :func:`Utils.encode`. 178 function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
177 179
178 * New :exc:`DeprecationWarning`\ s have been added to: 180 * New :exc:`DeprecationWarning`\ s have been added to:
179 :meth:`Generator.__call__`, :meth:`Message.get_type`, 181 :meth:`Generator.__call__`, :meth:`Message.get_type`,
180 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* 182 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
181 argument to the :class:`Parser` class. These are expected to be removed in 183 argument to the :class:`~email.parser.Parser` class. These are expected to
182 future versions. 184 be removed in future versions.
183 185
184 * Support for Pythons earlier than 2.3 has been removed. 186 * Support for Pythons earlier than 2.3 has been removed.
185 187
186 Here are the differences between :mod:`email` version 2 and version 1: 188 Here are the differences between :mod:`email` version 2 and version 1:
187 189
188 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added. 190 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
189 191
190 * The pickle format for :class:`Message` instances has changed. Since this was 192 * The pickle format for :class:`~email.message.Message` instances has changed.
191 never (and still isn't) formally defined, this isn't considered a backward 193 Since this was never (and still isn't) formally defined, this isn't
192 incompatibility. However if your application pickles and unpickles 194 considered a backward incompatibility. However if your application pickles
193 :class:`Message` instances, be aware that in :mod:`email` version 2, 195 and unpickles :class:`~email.message.Message` instances, be aware that in
194 :class:`Message` instances now have private variables *_charset* and 196 :mod:`email` version 2, :class:`~email.message.Message` instances now have
195 *_default_type*. 197 private variables *_charset* and *_default_type*.
196 198
197 * Several methods in the :class:`Message` class have been deprecated, or their 199 * Several methods in the :class:`~email.message.Message` class have been
198 signatures changed. Also, many new methods have been added. See the 200 deprecated, or their signatures changed. Also, many new methods have been
199 documentation for the :class:`Message` class for details. The changes should be 201 added. See the documentation for the :class:`~email.message.Message` class
200 completely backward compatible. 202 for details. The changes should be completely backward compatible.
201 203
202 * The object structure has changed in the face of :mimetype:`message/rfc822` 204 * The object structure has changed in the face of :mimetype:`message/rfc822`
203 content types. In :mod:`email` version 1, such a type would be represented by a 205 content types. In :mod:`email` version 1, such a type would be represented
204 scalar payload, i.e. the container message's :meth:`is_multipart` returned 206 by a scalar payload, i.e. the container message's
205 false, :meth:`get_payload` was not a list object, but a single :class:`Message ` 207 :meth:`~email.message.Message.is_multipart` returned false,
206 instance. 208 :meth:`~email.message.Message.get_payload` was not a list object, but a
209 single :class:`~email.message.Message` instance.
207 210
208 This structure was inconsistent with the rest of the package, so the object 211 This structure was inconsistent with the rest of the package, so the object
209 representation for :mimetype:`message/rfc822` content types was changed. In 212 representation for :mimetype:`message/rfc822` content types was changed. In
210 :mod:`email` version 2, the container *does* return ``True`` from 213 :mod:`email` version 2, the container *does* return ``True`` from
211 :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a sing le 214 :meth:`~email.message.Message.is_multipart`, and
212 :class:`Message` item. 215 :meth:`~email.message.Message.get_payload` returns a list containing a single
216 :class:`~email.message.Message` item.
213 217
214 Note that this is one place that backward compatibility could not be completel y 218 Note that this is one place that backward compatibility could not be
215 maintained. However, if you're already testing the return type of 219 completely maintained. However, if you're already testing the return type of
216 :meth:`get_payload`, you should be fine. You just need to make sure your code 220 :meth:`~email.message.Message.get_payload`, you should be fine. You just need
217 doesn't do a :meth:`set_payload` with a :class:`Message` instance on a contain er 221 to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
218 with a content type of :mimetype:`message/rfc822`. 222 with a :class:`~email.message.Message` instance on a container with a content
223 type of :mimetype:`message/rfc822`.
219 224
220 * The :class:`Parser` constructor's *strict* argument was added, and its 225 * The :class:`~email.parser.Parser` constructor's *strict* argument was added,
221 :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The 226 and its :meth:`~email.parser.Parser.parse` and
222 *strict* flag was also added to functions :func:`email.message_from_file` and 227 :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
223 :func:`email.message_from_string`. 228 The *strict* flag was also added to functions :func:`email.message_from_file`
229 and :func:`email.message_from_string`.
224 230
225 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten` 231 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
226 instead. The :class:`Generator` class has also grown the :meth:`clone` method . 232 <email.generator.Generator.flatten>` instead. The
233 :class:`~email.generator.Generator` class has also grown the
234 :meth:`~email.generator.Generator.clone` method.
227 235
228 * The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was 236 * The :class:`~email.generator.DecodedGenerator` class in the
229 added. 237 :mod:`email.generator` module was added.
230 238
231 * The intermediate base classes :class:`MIMENonMultipart` and 239 * The intermediate base classes
232 :class:`MIMEMultipart` have been added, and interposed in the class hierarchy 240 :class:`~email.mime.nonmultipart.MIMENonMultipart` and
233 for most of the other MIME-related derived classes. 241 :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
242 in the class hierarchy for most of the other MIME-related derived classes.
234 243
235 * The *_encoder* argument to the :class:`MIMEText` constructor has been 244 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
236 deprecated. Encoding now happens implicitly based on the *_charset* argument . 245 has been deprecated. Encoding now happens implicitly based on the
246 *_charset* argument.
237 247
238 * The following functions in the :mod:`email.Utils` module have been deprecated: 248 * The following functions in the :mod:`email.Utils` module have been deprecated:
239 :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following 249 :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
240 functions have been added to the module: :func:`make_msgid`, 250 functions have been added to the module: :func:`make_msgid`,
241 :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`. 251 :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
242 252
243 * The non-public function :func:`email.Iterators._structure` was added. 253 * The non-public function :func:`email.Iterators._structure` was added.
244 254
245 255
246 Differences from :mod:`mimelib` 256 Differences from :mod:`mimelib`
(...skipping 12 matching lines...) Expand all
259 the :mod:`email` packages, along with hints on how to port your applications. 269 the :mod:`email` packages, along with hints on how to port your applications.
260 270
261 Of course, the most visible difference between the two packages is that the 271 Of course, the most visible difference between the two packages is that the
262 package name has been changed to :mod:`email`. In addition, the top-level 272 package name has been changed to :mod:`email`. In addition, the top-level
263 package has the following differences: 273 package has the following differences:
264 274
265 * :func:`messageFromString` has been renamed to :func:`message_from_string`. 275 * :func:`messageFromString` has been renamed to :func:`message_from_string`.
266 276
267 * :func:`messageFromFile` has been renamed to :func:`message_from_file`. 277 * :func:`messageFromFile` has been renamed to :func:`message_from_file`.
268 278
269 The :class:`Message` class has the following differences: 279 The :class:`~email.message.Message` class has the following differences:
270 280
271 * The method :meth:`asString` was renamed to :meth:`as_string`. 281 * The method :meth:`asString` was renamed to
282 :meth:`~email.message.Message.as_string`.
272 283
273 * The method :meth:`ismultipart` was renamed to :meth:`is_multipart`. 284 * The method :meth:`ismultipart` was renamed to
285 :meth:`~email.message.Message.is_multipart`.
274 286
275 * The :meth:`get_payload` method has grown a *decode* optional argument. 287 * The :meth:`~email.message.Message.get_payload` method has grown a *decode*
288 optional argument.
276 289
277 * The method :meth:`getall` was renamed to :meth:`get_all`. 290 * The method :meth:`getall` was renamed to
291 :meth:`~email.message.Message.get_all`.
278 292
279 * The method :meth:`addheader` was renamed to :meth:`add_header`. 293 * The method :meth:`addheader` was renamed to
294 :meth:`~email.message.Message.add_header`.
280 295
281 * The method :meth:`gettype` was renamed to :meth:`get_type`. 296 * The method :meth:`gettype` was renamed to :meth:`get_type`.
282 297
283 * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`. 298 * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
284 299
285 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. 300 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
286 301
287 * The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas 302 * The method :meth:`getparams` was renamed to
288 :meth:`getparams` returned a list of strings, :meth:`get_params` returns a lis t 303 :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
289 of 2-tuples, effectively the key/value pairs of the parameters, split on the 304 returned a list of strings, :meth:`~email.message.Message.get_params` returns
290 ``'='`` sign. 305 a list of 2-tuples, effectively the key/value pairs of the parameters, split
306 on the ``'='`` sign.
291 307
292 * The method :meth:`getparam` was renamed to :meth:`get_param`. 308 * The method :meth:`getparam` was renamed to
309 :meth:`~email.message.Message.get_param`.
293 310
294 * The method :meth:`getcharsets` was renamed to :meth:`get_charsets`. 311 * The method :meth:`getcharsets` was renamed to
312 :meth:`~email.message.Message.get_charsets`.
295 313
296 * The method :meth:`getfilename` was renamed to :meth:`get_filename`. 314 * The method :meth:`getfilename` was renamed to
315 :meth:`~email.message.Message.get_filename`.
297 316
298 * The method :meth:`getboundary` was renamed to :meth:`get_boundary`. 317 * The method :meth:`getboundary` was renamed to
318 :meth:`~email.message.Message.get_boundary`.
299 319
300 * The method :meth:`setboundary` was renamed to :meth:`set_boundary`. 320 * The method :meth:`setboundary` was renamed to
321 :meth:`~email.message.Message.set_boundary`.
301 322
302 * The method :meth:`getdecodedpayload` was removed. To get similar 323 * The method :meth:`getdecodedpayload` was removed. To get similar
303 functionality, pass the value 1 to the *decode* flag of the get_payload() 324 functionality, pass the value 1 to the *decode* flag of the
304 method. 325 :meth:`~email.message.Message.get_payload` method.
305 326
306 * The method :meth:`getpayloadastext` was removed. Similar functionality is 327 * The method :meth:`getpayloadastext` was removed. Similar functionality is
307 supported by the :class:`DecodedGenerator` class in the :mod:`email.generator` 328 supported by the :class:`~email.generator.DecodedGenerator` class in the
329 :mod:`email.generator` module.
330
331 * The method :meth:`getbodyastext` was removed. You can get similar
332 functionality by creating an iterator with
333 :func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
308 module. 334 module.
309 335
310 * The method :meth:`getbodyastext` was removed. You can get similar 336 The :class:`~email.parser.Parser` class has no differences in its public
311 functionality by creating an iterator with :func:`typed_subpart_iterator` in t he 337 interface. It does have some additional smarts to recognize
312 :mod:`email.iterators` module. 338 :mimetype:`message/delivery-status` type messages, which it represents as a
339 :class:`~email.message.Message` instance containing separate
340 :class:`~email.message.Message` subparts for each header block in the delivery
341 status notification [#]_.
313 342
314 The :class:`Parser` class has no differences in its public interface. It does 343 The :class:`~email.generator.Generator` class has no differences in its public
315 have some additional smarts to recognize :mimetype:`message/delivery-status` 344 interface. There is a new class in the :mod:`email.generator` module though,
316 type messages, which it represents as a :class:`Message` instance containing 345 called :class:`~email.generator.DecodedGenerator` which provides most of the
317 separate :class:`Message` subparts for each header block in the delivery status 346 functionality previously available in the :meth:`Message.getpayloadastext`
318 notification [#]_. 347 method.
319
320 The :class:`Generator` class has no differences in its public interface. There
321 is a new class in the :mod:`email.generator` module though, called
322 :class:`DecodedGenerator` which provides most of the functionality previously
323 available in the :meth:`Message.getpayloadastext` method.
324 348
325 The following modules and classes have been changed: 349 The following modules and classes have been changed:
326 350
327 * The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have 351 * The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
328 changed to *_maintype* and *_subtype* respectively. 352 and *_minor* have changed to *_maintype* and *_subtype* respectively.
329 353
330 * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor* 354 * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
331 argument has been renamed to *_subtype*. 355 argument has been renamed to *_subtype*.
332 356
333 * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor* 357 * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
334 argument has been renamed to *_subtype*. 358 argument has been renamed to *_subtype*.
335 359
336 * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note 360 * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
337 that an earlier version of :mod:`mimelib` called this class/module ``RFC822``, 361 that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
338 but that clashed with the Python standard library module :mod:`rfc822` on some 362 but that clashed with the Python standard library module :mod:`rfc822` on some
339 case-insensitive file systems. 363 case-insensitive file systems.
340 364
341 Also, the :class:`MIMEMessage` class now represents any kind of MIME message 365 Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
366 kind of MIME message
342 with main type :mimetype:`message`. It takes an optional argument *_subtype* 367 with main type :mimetype:`message`. It takes an optional argument *_subtype*
343 which is used to set the MIME subtype. *_subtype* defaults to 368 which is used to set the MIME subtype. *_subtype* defaults to
344 :mimetype:`rfc822`. 369 :mimetype:`rfc822`.
345 370
346 :mod:`mimelib` provided some utility functions in its :mod:`address` and 371 :mod:`mimelib` provided some utility functions in its :mod:`address` and
347 :mod:`date` modules. All of these functions have been moved to the 372 :mod:`date` modules. All of these functions have been moved to the
348 :mod:`email.utils` module. 373 :mod:`email.utils` module.
349 374
350 The ``MsgReader`` class/module has been removed. Its functionality is most 375 The ``MsgReader`` class/module has been removed. Its functionality is most
351 closely supported in the :func:`body_line_iterator` function in the 376 closely supported in the :func:`~email.iterators.body_line_iterator` function
352 :mod:`email.iterators` module. 377 in the :mod:`email.iterators` module.
353 378
354 .. rubric:: Footnotes 379 .. rubric:: Footnotes
355 380
356 .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. 381 .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
OLDNEW
« no previous file with comments | « Doc/library/email.policy.rst ('k') | Doc/library/email.util.rst » ('j') | no next file with comments »

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