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

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

Issue 18761: Fix internal doc references for the email package (Closed)
Left Patch Set: Created 6 years, 9 months ago
Right Patch Set: Created 6 years, 9 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.policy.rst ('k') | Doc/library/email.util.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` --- 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 136 matching lines...) Expand 10 before | Expand all | Expand 10 after
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:`~email.mime.application.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:`~email.parser.FeedParser` class was introduced, and the :class:`~e mail.parser.Parser` class 167 * The :class:`~email.parser.FeedParser` class was introduced, and the
167 was implemented in terms of the :class:`~email.parser.FeedParser`. All parsin g 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:`~email.mime.text.MIMEText` constructor, the :meth:`Message.add_payload ` method, the 176 :class:`~email.mime.text.MIMEText` constructor, the
r.david.murray 2013/08/16 23:31:43 Don't we need ~email.message here as well?
storchaka 2013/08/18 21:39:21 Message.add_payload no more exists.
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:`~email.parser.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:`~email.message.Message` instances has changed. S ince 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:`~email.message.Message` instances, be aware that in :mod:`email` versi on 2, 195 and unpickles :class:`~email.message.Message` instances, be aware that in
194 :class:`~email.message.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:`~email.message.Message` class have been depreca ted, 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:`~email.message.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:`~email. message.Message` 207 :meth:`~email.message.Message.is_multipart` returned false,
r.david.murray 2013/08/16 23:31:43 Don't we need ~email.message.Message here?
storchaka 2013/08/18 21:39:21 Done.
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
215 :meth:`~email.message.Message.get_payload` returns a list containing a single
212 :class:`~email.message.Message` item. 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:`~email.message.Message` instan ce on a container 221 to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
r.david.murray 2013/08/16 23:31:43 ~email.message.Message.set_payload?
storchaka 2013/08/18 21:39:21 Done.
218 with a content type of :mimetype:`message/rfc822`. 222 with a :class:`~email.message.Message` instance on a container with a content
219 223 type of :mimetype:`message/rfc822`.
220 * The :class:`~email.parser.Parser` constructor's *strict* argument was added, a nd its 224
221 :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The 225 * The :class:`~email.parser.Parser` constructor's *strict* argument was added,
222 *strict* flag was also added to functions :func:`email.message_from_file` and 226 and its :meth:`~email.parser.Parser.parse` and
223 :func:`email.message_from_string`. 227 :meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
224 228 The *strict* flag was also added to functions :func:`email.message_from_file`
225 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten` 229 and :func:`email.message_from_string`.
226 instead. The :class:`~email.generator.Generator` class has also grown the :me th:`clone` method. 230
227 231 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
228 * The :class:`~email.generator.DecodedGenerator` class in the :mod:`email.genera tor` module was 232 <email.generator.Generator.flatten>` instead. The
229 added. 233 :class:`~email.generator.Generator` class has also grown the
230 234 :meth:`~email.generator.Generator.clone` method.
231 * The intermediate base classes :class:`~email.mime.nonmultipart.MIMENonMultipar t` and 235
232 :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed i n the class hierarchy 236 * The :class:`~email.generator.DecodedGenerator` class in the
233 for most of the other MIME-related derived classes. 237 :mod:`email.generator` module was added.
234 238
235 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor has been 239 * The intermediate base classes
236 deprecated. Encoding now happens implicitly based on the *_charset* argument . 240 :class:`~email.mime.nonmultipart.MIMENonMultipart` and
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.
243
244 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
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 14 matching lines...) Expand all
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:`~email.message.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:`~email.message.Message.as_st ring`. 281 * The method :meth:`asString` was renamed to
272 282 :meth:`~email.message.Message.as_string`.
273 * The method :meth:`ismultipart` was renamed to :meth:`~email.message.Message.is _multipart`. 283
274 284 * The method :meth:`ismultipart` was renamed to
275 * The :meth:`~email.message.Message.get_payload` method has grown a *decode* opt ional argument. 285 :meth:`~email.message.Message.is_multipart`.
276 286
277 * The method :meth:`getall` was renamed to :meth:`~email.message.Message.get_all `. 287 * The :meth:`~email.message.Message.get_payload` method has grown a *decode*
278 288 optional argument.
279 * The method :meth:`addheader` was renamed to :meth:`~email.message.Message.add_ header`. 289
280 290 * The method :meth:`getall` was renamed to
281 * The method :meth:`gettype` was renamed to :meth:`~email.message.Message.get_ty pe`. 291 :meth:`~email.message.Message.get_all`.
282 292
283 * The method :meth:`getmaintype` was renamed to :meth:`~email.message.Message.ge t_main_type`. 293 * The method :meth:`addheader` was renamed to
284 294 :meth:`~email.message.Message.add_header`.
285 * The method :meth:`getsubtype` was renamed to :meth:`~email.message.Message.get _subtype`. 295
286 296 * The method :meth:`gettype` was renamed to :meth:`get_type`.
287 * The method :meth:`getparams` was renamed to :meth:`~email.message.Message.get_ params`. Also, whereas 297
288 :meth:`getparams` returned a list of strings, :meth:`~email.message.Message.ge t_params` returns a list 298 * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
289 of 2-tuples, effectively the key/value pairs of the parameters, split on the 299
290 ``'='`` sign. 300 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
291 301
292 * The method :meth:`getparam` was renamed to :meth:`~email.message.Message.get_p aram`. 302 * The method :meth:`getparams` was renamed to
293 303 :meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
294 * The method :meth:`getcharsets` was renamed to :meth:`~email.message.Message.ge t_charsets`. 304 returned a list of strings, :meth:`~email.message.Message.get_params` returns
295 305 a list of 2-tuples, effectively the key/value pairs of the parameters, split
296 * The method :meth:`getfilename` was renamed to :meth:`~email.message.Message.ge t_filename`. 306 on the ``'='`` sign.
297 307
298 * The method :meth:`getboundary` was renamed to :meth:`~email.message.Message.ge t_boundary`. 308 * The method :meth:`getparam` was renamed to
299 309 :meth:`~email.message.Message.get_param`.
300 * The method :meth:`setboundary` was renamed to :meth:`~email.message.Message.se t_boundary`. 310
ezio.melotti 2013/08/16 23:38:47 Is there any way to either set a shortcut somewher
storchaka 2013/08/18 22:06:50 Yes, we can change current module and class. But t
311 * The method :meth:`getcharsets` was renamed to
312 :meth:`~email.message.Message.get_charsets`.
313
314 * The method :meth:`getfilename` was renamed to
315 :meth:`~email.message.Message.get_filename`.
316
317 * The method :meth:`getboundary` was renamed to
318 :meth:`~email.message.Message.get_boundary`.
319
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 :meth:`~email.mess age.Message.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:`~email.generator.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:`~email.iterators.typed_subpa rt_iterator` in the 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
313 339 :class:`~email.message.Message` instance containing separate
314 The :class:`~email.parser.Parser` class has no differences in its public interfa ce. It does 340 :class:`~email.message.Message` subparts for each header block in the delivery
315 have some additional smarts to recognize :mimetype:`message/delivery-status` 341 status notification [#]_.
316 type messages, which it represents as a :class:`~email.message.Message` instance containing 342
317 separate :class:`~email.message.Message` subparts for each header block in the d elivery status 343 The :class:`~email.generator.Generator` class has no differences in its public
318 notification [#]_. 344 interface. There is a new class in the :mod:`email.generator` module though,
319 345 called :class:`~email.generator.DecodedGenerator` which provides most of the
320 The :class:`~email.generator.Generator` class has no differences in its public i nterface. There 346 functionality previously available in the :meth:`Message.getpayloadastext`
321 is a new class in the :mod:`email.generator` module though, called 347 method.
322 :class:`~email.generator.DecodedGenerator` which provides most of the functional ity 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:`~email.mime.base.MIMEBase` class constructor arguments *_major* an d *_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:`~email.mime.message.MIMEMessage` class now represents any ki nd 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:`~email.iterators.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`.
LEFTRIGHT

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