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

Side by Side Diff: Doc/library/email.message.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.message`: Representing an email message 1 :mod:`email.message`: Representing an email message
2 --------------------------------------------------- 2 ---------------------------------------------------
3 3
4 .. module:: email.message 4 .. module:: email.message
5 :synopsis: The base class representing email messages. 5 :synopsis: The base class representing email messages.
6 6
7 7
8 The central class in the :mod:`email` package is the :class:`Message` class, 8 The central class in the :mod:`email` package is the :class:`Message` class,
9 imported from the :mod:`email.message` module. It is the base class for the 9 imported from the :mod:`email.message` module. It is the base class for the
10 :mod:`email` object model. :class:`Message` provides the core functionality for 10 :mod:`email` object model. :class:`Message` provides the core functionality for
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after
55 method, since the specified *policy* will be passed to the ``Generator``. 55 method, since the specified *policy* will be passed to the ``Generator``.
56 56
57 Flattening the message may trigger changes to the :class:`Message` if 57 Flattening the message may trigger changes to the :class:`Message` if
58 defaults need to be filled in to complete the transformation to a string 58 defaults need to be filled in to complete the transformation to a string
59 (for example, MIME boundaries may be generated or modified). 59 (for example, MIME boundaries may be generated or modified).
60 60
61 Note that this method is provided as a convenience and may not always 61 Note that this method is provided as a convenience and may not always
62 format the message the way you want. For example, by default it does 62 format the message the way you want. For example, by default it does
63 not do the mangling of lines that begin with ``From`` that is 63 not do the mangling of lines that begin with ``From`` that is
64 required by the unix mbox format. For more flexibility, instantiate a 64 required by the unix mbox format. For more flexibility, instantiate a
65 :class:`~email.generator.Generator` instance and use its :meth:`flatten` 65 :class:`~email.generator.Generator` instance and use its :meth:`~email.gen erator.Generator.flatten`
66 method directly. For example:: 66 method directly. For example::
67 67
68 from io import StringIO 68 from io import StringIO
69 from email.generator import Generator 69 from email.generator import Generator
70 fp = StringIO() 70 fp = StringIO()
71 g = Generator(fp, mangle_from_=True, maxheaderlen=60) 71 g = Generator(fp, mangle_from_=True, maxheaderlen=60)
72 g.flatten(msg) 72 g.flatten(msg)
73 text = fp.getvalue() 73 text = fp.getvalue()
74 74
75 If the message object contains binary data that is not encoded according 75 If the message object contains binary data that is not encoded according
(...skipping 22 matching lines...) Expand all
98 98
99 Flattening the message may trigger changes to the :class:`Message` if 99 Flattening the message may trigger changes to the :class:`Message` if
100 defaults need to be filled in to complete the transformation to a string 100 defaults need to be filled in to complete the transformation to a string
101 (for example, MIME boundaries may be generated or modified). 101 (for example, MIME boundaries may be generated or modified).
102 102
103 Note that this method is provided as a convenience and may not always 103 Note that this method is provided as a convenience and may not always
104 format the message the way you want. For example, by default it does 104 format the message the way you want. For example, by default it does
105 not do the mangling of lines that begin with ``From`` that is 105 not do the mangling of lines that begin with ``From`` that is
106 required by the unix mbox format. For more flexibility, instantiate a 106 required by the unix mbox format. For more flexibility, instantiate a
107 :class:`~email.generator.BytesGenerator` instance and use its 107 :class:`~email.generator.BytesGenerator` instance and use its
108 :meth:`flatten` method directly. For example:: 108 :meth:`~email.generator.BytesGenerator.flatten` method directly. For exam ple::
109 109
110 from io import BytesIO 110 from io import BytesIO
111 from email.generator import BytesGenerator 111 from email.generator import BytesGenerator
112 fp = BytesIO() 112 fp = BytesIO()
113 g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60) 113 g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
114 g.flatten(msg) 114 g.flatten(msg)
115 text = fp.getvalue() 115 text = fp.getvalue()
116 116
117 .. versionadded:: 3.4 117 .. versionadded:: 3.4
118 118
(...skipping 187 matching lines...) Expand 10 before | Expand all | Expand 10 after
306 306
307 .. method:: items() 307 .. method:: items()
308 308
309 Return a list of 2-tuples containing all the message's field headers and 309 Return a list of 2-tuples containing all the message's field headers and
310 values. 310 values.
311 311
312 312
313 .. method:: get(name, failobj=None) 313 .. method:: get(name, failobj=None)
314 314
315 Return the value of the named header field. This is identical to 315 Return the value of the named header field. This is identical to
316 :meth:`__getitem__` except that optional *failobj* is returned if the 316 :meth:`~object.__getitem__` except that optional *failobj* is returned if the
r.david.murray 2013/08/16 23:31:43 This change is incorrect. The original construct
storchaka 2013/08/18 21:39:21 Done.
317 named header is missing (defaults to ``None``). 317 named header is missing (defaults to ``None``).
318 318
319 Here are some additional useful methods: 319 Here are some additional useful methods:
320 320
321 321
322 .. method:: get_all(name, failobj=None) 322 .. method:: get_all(name, failobj=None)
323 323
324 Return a list of all the values for the field named *name*. If there are 324 Return a list of all the values for the field named *name*. If there are
325 no such named headers in the message, *failobj* is returned (defaults to 325 no such named headers in the message, *failobj* is returned (defaults to
326 ``None``). 326 ``None``).
327 327
328 328
329 .. method:: add_header(_name, _value, **_params) 329 .. method:: add_header(_name, _value, **_params)
330 330
331 Extended header setting. This method is similar to :meth:`__setitem__` 331 Extended header setting. This method is similar to :meth:`~object.__setit em__`
r.david.murray 2013/08/16 23:31:43 This change is also incorrect.
storchaka 2013/08/18 21:39:21 Done.
332 except that additional header parameters can be provided as keyword 332 except that additional header parameters can be provided as keyword
333 arguments. *_name* is the header field to add and *_value* is the 333 arguments. *_name* is the header field to add and *_value* is the
334 *primary* value for the header. 334 *primary* value for the header.
335 335
336 For each item in the keyword argument dictionary *_params*, the key is 336 For each item in the keyword argument dictionary *_params*, the key is
337 taken as the parameter name, with underscores converted to dashes (since 337 taken as the parameter name, with underscores converted to dashes (since
338 dashes are illegal in Python identifiers). Normally, the parameter will 338 dashes are illegal in Python identifiers). Normally, the parameter will
339 be added as ``key="value"`` unless the value is ``None``, in which case 339 be added as ``key="value"`` unless the value is ``None``, in which case
340 only the key will be added. If the value contains non-ASCII characters, 340 only the key will be added. If the value contains non-ASCII characters,
341 it can be specified as a three tuple in the format 341 it can be specified as a three tuple in the format
(...skipping 181 matching lines...) Expand 10 before | Expand all | Expand 10 after
523 Return the value of the ``boundary`` parameter of the 523 Return the value of the ``boundary`` parameter of the
524 :mailheader:`Content-Type` header of the message, or *failobj* if either 524 :mailheader:`Content-Type` header of the message, or *failobj* if either
525 the header is missing, or has no ``boundary`` parameter. The returned 525 the header is missing, or has no ``boundary`` parameter. The returned
526 string will always be unquoted as per :func:`email.utils.unquote`. 526 string will always be unquoted as per :func:`email.utils.unquote`.
527 527
528 528
529 .. method:: set_boundary(boundary) 529 .. method:: set_boundary(boundary)
530 530
531 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to 531 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
532 *boundary*. :meth:`set_boundary` will always quote *boundary* if 532 *boundary*. :meth:`set_boundary` will always quote *boundary* if
533 necessary. A :exc:`HeaderParseError` is raised if the message object has 533 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the messa ge object has
534 no :mailheader:`Content-Type` header. 534 no :mailheader:`Content-Type` header.
535 535
536 Note that using this method is subtly different than deleting the old 536 Note that using this method is subtly different than deleting the old
537 :mailheader:`Content-Type` header and adding a new one with the new 537 :mailheader:`Content-Type` header and adding a new one with the new
538 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves 538 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
539 the order of the :mailheader:`Content-Type` header in the list of 539 the order of the :mailheader:`Content-Type` header in the list of
540 headers. However, it does *not* preserve any continuation lines which may 540 headers. However, it does *not* preserve any continuation lines which may
541 have been present in the original :mailheader:`Content-Type` header. 541 have been present in the original :mailheader:`Content-Type` header.
542 542
543 543
(...skipping 76 matching lines...) Expand 10 before | Expand all | Expand 10 after
620 will be ``None``. 620 will be ``None``.
621 621
622 622
623 .. attribute:: epilogue 623 .. attribute:: epilogue
624 624
625 The *epilogue* attribute acts the same way as the *preamble* attribute, 625 The *epilogue* attribute acts the same way as the *preamble* attribute,
626 except that it contains text that appears between the last boundary and 626 except that it contains text that appears between the last boundary and
627 the end of the message. 627 the end of the message.
628 628
629 You do not need to set the epilogue to the empty string in order for the 629 You do not need to set the epilogue to the empty string in order for the
630 :class:`Generator` to print a newline at the end of the file. 630 :class:`~email.generator.Generator` to print a newline at the end of the f ile.
631 631
632 632
633 .. attribute:: defects 633 .. attribute:: defects
634 634
635 The *defects* attribute contains a list of all the problems found when 635 The *defects* attribute contains a list of all the problems found when
636 parsing this message. See :mod:`email.errors` for a detailed description 636 parsing this message. See :mod:`email.errors` for a detailed description
637 of the possible parsing defects. 637 of the possible parsing defects.
OLDNEW

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