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

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

Issue 18761: Fix internal doc references for the email package (Closed)
Patch Set: Created 6 years, 3 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
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` and friends. Under some
158 circumstances, values which used to return a 3-tuple now return simple strings 158 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 159 (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 160 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 161 string). Also, %-decoding used to be done for both encoded and unencoded
162 segments; this decoding is now done only for encoded segments. 162 segments; this decoding is now done only for encoded segments.
163 163
164 Here are the major differences between :mod:`email` version 3 and version 2: 164 Here are the major differences between :mod:`email` version 3 and version 2:
165 165
166 * The :class:`FeedParser` class was introduced, and the :class:`Parser` class 166 * The :class:`~email.parser.FeedParser` class was introduced, and the :class:`~e mail.parser.Parser` class
167 was implemented in terms of the :class:`FeedParser`. All parsing therefore is 167 was implemented in terms of the :class:`~email.parser.FeedParser`. All parsin g therefore is
168 non-strict, and parsing will make a best effort never to raise an exception. 168 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* 169 Problems found while parsing messages are stored in the message's *defect*
170 attribute. 170 attribute.
171 171
172 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2 172 * All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
173 have been removed. These include the *_encoder* argument to the 173 have been removed. These include the *_encoder* argument to the
174 :class:`MIMEText` constructor, the :meth:`Message.add_payload` method, the 174 :class:`~email.mime.text.MIMEText` constructor, the :meth:`Message.add_payload ` method, 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` 175 :func:`Utils.dump_address_pair` function, and the functions :func:`Utils.decod e`
176 and :func:`Utils.encode`. 176 and :func:`Utils.encode`.
177 177
178 * New :exc:`DeprecationWarning`\ s have been added to: 178 * New :exc:`DeprecationWarning`\ s have been added to:
179 :meth:`Generator.__call__`, :meth:`Message.get_type`, 179 :meth:`Generator.__call__`, :meth:`Message.get_type`,
180 :meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict* 180 :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 181 argument to the :class:`~email.parser.Parser` class. These are expected to be removed in
182 future versions. 182 future versions.
183 183
184 * Support for Pythons earlier than 2.3 has been removed. 184 * Support for Pythons earlier than 2.3 has been removed.
185 185
186 Here are the differences between :mod:`email` version 2 and version 1: 186 Here are the differences between :mod:`email` version 2 and version 1:
187 187
188 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added. 188 * The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
189 189
190 * The pickle format for :class:`Message` instances has changed. Since this was 190 * The pickle format for :class:`~email.message.Message` instances has changed. S ince this was
191 never (and still isn't) formally defined, this isn't considered a backward 191 never (and still isn't) formally defined, this isn't considered a backward
192 incompatibility. However if your application pickles and unpickles 192 incompatibility. However if your application pickles and unpickles
193 :class:`Message` instances, be aware that in :mod:`email` version 2, 193 :class:`~email.message.Message` instances, be aware that in :mod:`email` versi on 2,
194 :class:`Message` instances now have private variables *_charset* and 194 :class:`~email.message.Message` instances now have private variables *_charset * and
195 *_default_type*. 195 *_default_type*.
196 196
197 * Several methods in the :class:`Message` class have been deprecated, or their 197 * Several methods in the :class:`~email.message.Message` class have been depreca ted, or their
198 signatures changed. Also, many new methods have been added. See the 198 signatures changed. Also, many new methods have been added. See the
199 documentation for the :class:`Message` class for details. The changes should be 199 documentation for the :class:`~email.message.Message` class for details. The changes should be
200 completely backward compatible. 200 completely backward compatible.
201 201
202 * The object structure has changed in the face of :mimetype:`message/rfc822` 202 * 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 203 content types. In :mod:`email` version 1, such a type would be represented by a
204 scalar payload, i.e. the container message's :meth:`is_multipart` returned 204 scalar payload, i.e. the container message's :meth:`is_multipart` returned
205 false, :meth:`get_payload` was not a list object, but a single :class:`Message ` 205 false, :meth:`get_payload` was not a list object, but a single :class:`~email. message.Message`
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. 206 instance.
207 207
208 This structure was inconsistent with the rest of the package, so the object 208 This structure was inconsistent with the rest of the package, so the object
209 representation for :mimetype:`message/rfc822` content types was changed. In 209 representation for :mimetype:`message/rfc822` content types was changed. In
210 :mod:`email` version 2, the container *does* return ``True`` from 210 :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 211 :meth:`is_multipart`, and :meth:`get_payload` returns a list containing a sing le
212 :class:`Message` item. 212 :class:`~email.message.Message` item.
213 213
214 Note that this is one place that backward compatibility could not be completel y 214 Note that this is one place that backward compatibility could not be completel y
215 maintained. However, if you're already testing the return type of 215 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 216 :meth:`get_payload`, you should be fine. You just need to make sure your code
217 doesn't do a :meth:`set_payload` with a :class:`Message` instance on a contain er 217 doesn't do a :meth:`set_payload` with a :class:`~email.message.Message` instan ce on a container
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`. 218 with a content type of :mimetype:`message/rfc822`.
219 219
220 * The :class:`Parser` constructor's *strict* argument was added, and its 220 * The :class:`~email.parser.Parser` constructor's *strict* argument was added, a nd its
221 :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The 221 :meth:`parse` and :meth:`parsestr` methods grew a *headersonly* argument. The
222 *strict* flag was also added to functions :func:`email.message_from_file` and 222 *strict* flag was also added to functions :func:`email.message_from_file` and
223 :func:`email.message_from_string`. 223 :func:`email.message_from_string`.
224 224
225 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten` 225 * :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten`
226 instead. The :class:`Generator` class has also grown the :meth:`clone` method . 226 instead. The :class:`~email.generator.Generator` class has also grown the :me th:`clone` method.
227 227
228 * The :class:`DecodedGenerator` class in the :mod:`email.Generator` module was 228 * The :class:`~email.generator.DecodedGenerator` class in the :mod:`email.genera tor` module was
229 added. 229 added.
230 230
231 * The intermediate base classes :class:`MIMENonMultipart` and 231 * The intermediate base classes :class:`~email.mime.nonmultipart.MIMENonMultipar t` and
232 :class:`MIMEMultipart` have been added, and interposed in the class hierarchy 232 :class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed i n the class hierarchy
233 for most of the other MIME-related derived classes. 233 for most of the other MIME-related derived classes.
234 234
235 * The *_encoder* argument to the :class:`MIMEText` constructor has been 235 * The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor has been
236 deprecated. Encoding now happens implicitly based on the *_charset* argument . 236 deprecated. Encoding now happens implicitly based on the *_charset* argument .
237 237
238 * The following functions in the :mod:`email.Utils` module have been deprecated: 238 * The following functions in the :mod:`email.Utils` module have been deprecated:
239 :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following 239 :func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
240 functions have been added to the module: :func:`make_msgid`, 240 functions have been added to the module: :func:`make_msgid`,
241 :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`. 241 :func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
242 242
243 * The non-public function :func:`email.Iterators._structure` was added. 243 * The non-public function :func:`email.Iterators._structure` was added.
244 244
245 245
(...skipping 13 matching lines...) Expand all
259 the :mod:`email` packages, along with hints on how to port your applications. 259 the :mod:`email` packages, along with hints on how to port your applications.
260 260
261 Of course, the most visible difference between the two packages is that the 261 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 262 package name has been changed to :mod:`email`. In addition, the top-level
263 package has the following differences: 263 package has the following differences:
264 264
265 * :func:`messageFromString` has been renamed to :func:`message_from_string`. 265 * :func:`messageFromString` has been renamed to :func:`message_from_string`.
266 266
267 * :func:`messageFromFile` has been renamed to :func:`message_from_file`. 267 * :func:`messageFromFile` has been renamed to :func:`message_from_file`.
268 268
269 The :class:`Message` class has the following differences: 269 The :class:`~email.message.Message` class has the following differences:
270 270
271 * The method :meth:`asString` was renamed to :meth:`as_string`. 271 * The method :meth:`asString` was renamed to :meth:`~email.message.Message.as_st ring`.
272 272
273 * The method :meth:`ismultipart` was renamed to :meth:`is_multipart`. 273 * The method :meth:`ismultipart` was renamed to :meth:`~email.message.Message.is _multipart`.
274 274
275 * The :meth:`get_payload` method has grown a *decode* optional argument. 275 * The :meth:`~email.message.Message.get_payload` method has grown a *decode* opt ional argument.
276 276
277 * The method :meth:`getall` was renamed to :meth:`get_all`. 277 * The method :meth:`getall` was renamed to :meth:`~email.message.Message.get_all `.
278 278
279 * The method :meth:`addheader` was renamed to :meth:`add_header`. 279 * The method :meth:`addheader` was renamed to :meth:`~email.message.Message.add_ header`.
280 280
281 * The method :meth:`gettype` was renamed to :meth:`get_type`. 281 * The method :meth:`gettype` was renamed to :meth:`~email.message.Message.get_ty pe`.
282 282
283 * The method :meth:`getmaintype` was renamed to :meth:`get_main_type`. 283 * The method :meth:`getmaintype` was renamed to :meth:`~email.message.Message.ge t_main_type`.
284 284
285 * The method :meth:`getsubtype` was renamed to :meth:`get_subtype`. 285 * The method :meth:`getsubtype` was renamed to :meth:`~email.message.Message.get _subtype`.
286 286
287 * The method :meth:`getparams` was renamed to :meth:`get_params`. Also, whereas 287 * The method :meth:`getparams` was renamed to :meth:`~email.message.Message.get_ params`. Also, whereas
288 :meth:`getparams` returned a list of strings, :meth:`get_params` returns a lis t 288 :meth:`getparams` returned a list of strings, :meth:`~email.message.Message.ge t_params` returns a list
289 of 2-tuples, effectively the key/value pairs of the parameters, split on the 289 of 2-tuples, effectively the key/value pairs of the parameters, split on the
290 ``'='`` sign. 290 ``'='`` sign.
291 291
292 * The method :meth:`getparam` was renamed to :meth:`get_param`. 292 * The method :meth:`getparam` was renamed to :meth:`~email.message.Message.get_p aram`.
293 293
294 * The method :meth:`getcharsets` was renamed to :meth:`get_charsets`. 294 * The method :meth:`getcharsets` was renamed to :meth:`~email.message.Message.ge t_charsets`.
295 295
296 * The method :meth:`getfilename` was renamed to :meth:`get_filename`. 296 * The method :meth:`getfilename` was renamed to :meth:`~email.message.Message.ge t_filename`.
297 297
298 * The method :meth:`getboundary` was renamed to :meth:`get_boundary`. 298 * The method :meth:`getboundary` was renamed to :meth:`~email.message.Message.ge t_boundary`.
299 299
300 * The method :meth:`setboundary` was renamed to :meth:`set_boundary`. 300 * The method :meth:`setboundary` was renamed to :meth:`~email.message.Message.se t_boundary`.
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
301 301
302 * The method :meth:`getdecodedpayload` was removed. To get similar 302 * The method :meth:`getdecodedpayload` was removed. To get similar
303 functionality, pass the value 1 to the *decode* flag of the get_payload() 303 functionality, pass the value 1 to the *decode* flag of the :meth:`~email.mess age.Message.get_payload`
304 method. 304 method.
305 305
306 * The method :meth:`getpayloadastext` was removed. Similar functionality is 306 * The method :meth:`getpayloadastext` was removed. Similar functionality is
307 supported by the :class:`DecodedGenerator` class in the :mod:`email.generator` 307 supported by the :class:`~email.generator.DecodedGenerator` class in the :mod: `email.generator`
308 module. 308 module.
309 309
310 * The method :meth:`getbodyastext` was removed. You can get similar 310 * The method :meth:`getbodyastext` was removed. You can get similar
311 functionality by creating an iterator with :func:`typed_subpart_iterator` in t he 311 functionality by creating an iterator with :func:`~email.iterators.typed_subpa rt_iterator` in the
312 :mod:`email.iterators` module. 312 :mod:`email.iterators` module.
313 313
314 The :class:`Parser` class has no differences in its public interface. It does 314 The :class:`~email.parser.Parser` class has no differences in its public interfa ce. It does
315 have some additional smarts to recognize :mimetype:`message/delivery-status` 315 have some additional smarts to recognize :mimetype:`message/delivery-status`
316 type messages, which it represents as a :class:`Message` instance containing 316 type messages, which it represents as a :class:`~email.message.Message` instance containing
317 separate :class:`Message` subparts for each header block in the delivery status 317 separate :class:`~email.message.Message` subparts for each header block in the d elivery status
318 notification [#]_. 318 notification [#]_.
319 319
320 The :class:`Generator` class has no differences in its public interface. There 320 The :class:`~email.generator.Generator` class has no differences in its public i nterface. There
321 is a new class in the :mod:`email.generator` module though, called 321 is a new class in the :mod:`email.generator` module though, called
322 :class:`DecodedGenerator` which provides most of the functionality previously 322 :class:`~email.generator.DecodedGenerator` which provides most of the functional ity previously
323 available in the :meth:`Message.getpayloadastext` method. 323 available in the :meth:`Message.getpayloadastext` method.
324 324
325 The following modules and classes have been changed: 325 The following modules and classes have been changed:
326 326
327 * The :class:`MIMEBase` class constructor arguments *_major* and *_minor* have 327 * The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major* an d *_minor* have
328 changed to *_maintype* and *_subtype* respectively. 328 changed to *_maintype* and *_subtype* respectively.
329 329
330 * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor* 330 * The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
331 argument has been renamed to *_subtype*. 331 argument has been renamed to *_subtype*.
332 332
333 * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor* 333 * The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
334 argument has been renamed to *_subtype*. 334 argument has been renamed to *_subtype*.
335 335
336 * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note 336 * The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
337 that an earlier version of :mod:`mimelib` called this class/module ``RFC822``, 337 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 338 but that clashed with the Python standard library module :mod:`rfc822` on some
339 case-insensitive file systems. 339 case-insensitive file systems.
340 340
341 Also, the :class:`MIMEMessage` class now represents any kind of MIME message 341 Also, the :class:`~email.mime.message.MIMEMessage` class now represents any ki nd of MIME message
342 with main type :mimetype:`message`. It takes an optional argument *_subtype* 342 with main type :mimetype:`message`. It takes an optional argument *_subtype*
343 which is used to set the MIME subtype. *_subtype* defaults to 343 which is used to set the MIME subtype. *_subtype* defaults to
344 :mimetype:`rfc822`. 344 :mimetype:`rfc822`.
345 345
346 :mod:`mimelib` provided some utility functions in its :mod:`address` and 346 :mod:`mimelib` provided some utility functions in its :mod:`address` and
347 :mod:`date` modules. All of these functions have been moved to the 347 :mod:`date` modules. All of these functions have been moved to the
348 :mod:`email.utils` module. 348 :mod:`email.utils` module.
349 349
350 The ``MsgReader`` class/module has been removed. Its functionality is most 350 The ``MsgReader`` class/module has been removed. Its functionality is most
351 closely supported in the :func:`body_line_iterator` function in the 351 closely supported in the :func:`~email.iterators.body_line_iterator` function in the
352 :mod:`email.iterators` module. 352 :mod:`email.iterators` module.
353 353
354 .. rubric:: Footnotes 354 .. rubric:: Footnotes
355 355
356 .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. 356 .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
OLDNEW

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