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

Delta Between Two Patch Sets: Doc/library/email.message.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.iterators.rst ('k') | Doc/library/email.mime.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.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:`~email.gen erator.Generator.flatten` 65 :class:`~email.generator.Generator` instance and use its
66 method directly. For example:: 66 :meth:`~email.generator.Generator.flatten` 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
76 to RFC standards, the non-compliant data will be replaced by unicode 76 to RFC standards, the non-compliant data will be replaced by unicode
(...skipping 21 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:`~email.generator.BytesGenerator.flatten` method directly. For exam ple:: 108 :meth:`~email.generator.BytesGenerator.flatten` method directly.
109 For example::
109 110
110 from io import BytesIO 111 from io import BytesIO
111 from email.generator import BytesGenerator 112 from email.generator import BytesGenerator
112 fp = BytesIO() 113 fp = BytesIO()
113 g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60) 114 g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
114 g.flatten(msg) 115 g.flatten(msg)
115 text = fp.getvalue() 116 text = fp.getvalue()
116 117
117 .. versionadded:: 3.4 118 .. versionadded:: 3.4
118 119
(...skipping 187 matching lines...) Expand 10 before | Expand all | Expand 10 after
306 307
307 .. method:: items() 308 .. method:: items()
308 309
309 Return a list of 2-tuples containing all the message's field headers and 310 Return a list of 2-tuples containing all the message's field headers and
310 values. 311 values.
311 312
312 313
313 .. method:: get(name, failobj=None) 314 .. method:: get(name, failobj=None)
314 315
315 Return the value of the named header field. This is identical to 316 Return the value of the named header field. This is identical to
316 :meth:`~object.__getitem__` except that optional *failobj* is returned if the 317 :meth:`__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``). 318 named header is missing (defaults to ``None``).
318 319
319 Here are some additional useful methods: 320 Here are some additional useful methods:
320 321
321 322
322 .. method:: get_all(name, failobj=None) 323 .. method:: get_all(name, failobj=None)
323 324
324 Return a list of all the values for the field named *name*. If there are 325 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 326 no such named headers in the message, *failobj* is returned (defaults to
326 ``None``). 327 ``None``).
327 328
328 329
329 .. method:: add_header(_name, _value, **_params) 330 .. method:: add_header(_name, _value, **_params)
330 331
331 Extended header setting. This method is similar to :meth:`~object.__setit em__` 332 Extended header setting. This method is similar to :meth:`__setitem__`
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 333 except that additional header parameters can be provided as keyword
333 arguments. *_name* is the header field to add and *_value* is the 334 arguments. *_name* is the header field to add and *_value* is the
334 *primary* value for the header. 335 *primary* value for the header.
335 336
336 For each item in the keyword argument dictionary *_params*, the key is 337 For each item in the keyword argument dictionary *_params*, the key is
337 taken as the parameter name, with underscores converted to dashes (since 338 taken as the parameter name, with underscores converted to dashes (since
338 dashes are illegal in Python identifiers). Normally, the parameter will 339 dashes are illegal in Python identifiers). Normally, the parameter will
339 be added as ``key="value"`` unless the value is ``None``, in which case 340 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, 341 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 342 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 524 Return the value of the ``boundary`` parameter of the
524 :mailheader:`Content-Type` header of the message, or *failobj* if either 525 :mailheader:`Content-Type` header of the message, or *failobj* if either
525 the header is missing, or has no ``boundary`` parameter. The returned 526 the header is missing, or has no ``boundary`` parameter. The returned
526 string will always be unquoted as per :func:`email.utils.unquote`. 527 string will always be unquoted as per :func:`email.utils.unquote`.
527 528
528 529
529 .. method:: set_boundary(boundary) 530 .. method:: set_boundary(boundary)
530 531
531 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to 532 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
532 *boundary*. :meth:`set_boundary` will always quote *boundary* if 533 *boundary*. :meth:`set_boundary` will always quote *boundary* if
533 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the messa ge object has 534 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
534 no :mailheader:`Content-Type` header. 535 message object has no :mailheader:`Content-Type` header.
535 536
536 Note that using this method is subtly different than deleting the old 537 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 538 :mailheader:`Content-Type` header and adding a new one with the new
538 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves 539 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
539 the order of the :mailheader:`Content-Type` header in the list of 540 the order of the :mailheader:`Content-Type` header in the list of
540 headers. However, it does *not* preserve any continuation lines which may 541 headers. However, it does *not* preserve any continuation lines which may
541 have been present in the original :mailheader:`Content-Type` header. 542 have been present in the original :mailheader:`Content-Type` header.
542 543
543 544
544 .. method:: get_content_charset(failobj=None) 545 .. method:: get_content_charset(failobj=None)
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after
620 will be ``None``. 621 will be ``None``.
621 622
622 623
623 .. attribute:: epilogue 624 .. attribute:: epilogue
624 625
625 The *epilogue* attribute acts the same way as the *preamble* attribute, 626 The *epilogue* attribute acts the same way as the *preamble* attribute,
626 except that it contains text that appears between the last boundary and 627 except that it contains text that appears between the last boundary and
627 the end of the message. 628 the end of the message.
628 629
629 You do not need to set the epilogue to the empty string in order for the 630 You do not need to set the epilogue to the empty string in order for the
630 :class:`~email.generator.Generator` to print a newline at the end of the f ile. 631 :class:`~email.generator.Generator` to print a newline at the end of the
632 file.
631 633
632 634
633 .. attribute:: defects 635 .. attribute:: defects
634 636
635 The *defects* attribute contains a list of all the problems found when 637 The *defects* attribute contains a list of all the problems found when
636 parsing this message. See :mod:`email.errors` for a detailed description 638 parsing this message. See :mod:`email.errors` for a detailed description
637 of the possible parsing defects. 639 of the possible parsing defects.
LEFTRIGHT

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