From 748c958f2f495fb7ffcd700dabc11782bd4dcd7c Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 9 Jul 2024 12:44:10 -0400 Subject: [PATCH 1/4] Document trailing newline behavior in set_content() --- Doc/library/email.message.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index e9cce1af186526..926bde0d38cc4d 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -612,6 +612,13 @@ message objects. *content_manager* is not specified, use the ``content_manager`` specified by the current :mod:`~email.policy`. + Note that this method will append a newline character to the end of the + content, if it wasn't passed already. For example, the following are equivalent :: + + msg = EmailMessage() + msg.set_content("hello") + msg.set_content("hello\n") + .. method:: make_related(boundary=None) From 735ed1d0d27753d6af67c272a10555bb58b6a73e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 10 Jul 2024 08:13:19 -0400 Subject: [PATCH 2/4] Update email.message.rst --- Doc/library/email.message.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index 926bde0d38cc4d..e9cce1af186526 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -612,13 +612,6 @@ message objects. *content_manager* is not specified, use the ``content_manager`` specified by the current :mod:`~email.policy`. - Note that this method will append a newline character to the end of the - content, if it wasn't passed already. For example, the following are equivalent :: - - msg = EmailMessage() - msg.set_content("hello") - msg.set_content("hello\n") - .. method:: make_related(boundary=None) From 24b245a86272549e5c7c0f452f01e594415034eb Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 10 Jul 2024 08:17:42 -0400 Subject: [PATCH 3/4] Update email.contentmanager.rst --- Doc/library/email.contentmanager.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst index 34121f8c0a7727..bf917c84cdabf5 100644 --- a/Doc/library/email.contentmanager.rst +++ b/Doc/library/email.contentmanager.rst @@ -191,6 +191,13 @@ Currently the email package provides only one concrete content manager, (distinguished from strings by having a ``name`` attribute), add the headers to *msg*. + Note that this method will append a newline character to the end of strings, + if it wasn't passed already. For example, the following are equivalent :: + + msg = EmailMessage() + msg.set_content("hello") + msg.set_content("hello\n") + .. rubric:: Footnotes From 29cb612796f04ea0697a974cf26e696ba0ecf638 Mon Sep 17 00:00:00 2001 From: Yizheng Meng Date: Thu, 18 Jul 2024 16:54:39 +0800 Subject: [PATCH 4/4] Re-phrase docs of set_content behavior for str payloads The previous patch only illustrates this behavior with a very specific edge case, which IMO did not do a good job elucidating the present ambiguous documentation, if not worsening it by obscuring the true intention behind EOL canonicalization for messages of text/* types. This instead should address the more general case, abeit less concrete, which seems like a fair compromise, considering users who care about accurate representation of line endings will likely carefully study the documentation and be assured that this is an expected deviation from the legacy API, while those who do not are not befuddled by a footnote that seems to warn of something out of the blue. I do not know if this is true to the original author's intention, but it is my personal understanding of this implementation at least. :/ The case of bytes is also addressed briefly in a subsequent bullet point to assure the user that it is to be expected that all bytes are preserved as any arbitrary binary file ought to be. I wish I could state this more explicitly, but that seems rather hard without presumably restructuring this particular page, so I will leave it to the original author... :) Signed-off-by: Yizheng Meng --- Doc/library/email.contentmanager.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst index bf917c84cdabf5..f4d162fd967caa 100644 --- a/Doc/library/email.contentmanager.rst +++ b/Doc/library/email.contentmanager.rst @@ -156,7 +156,13 @@ Currently the email package provides only one concrete content manager, :exc:`ValueError`. * For ``str`` objects, if *cte* is not set use heuristics to - determine the most compact encoding. + determine the most compact encoding. Prior to encoding, + :meth:`str.splitlines` is used to normalize all line boundaries, + ensuring that each line of the payload is terminated by the + current policy's :data:`~email.policy.Policy.linesep` property + (even if the original string did not end with one). + * For ``bytes`` objects, *cte* is taken to be base64 if not set, + and the aforementioned newline translation is not performed. * For :class:`~email.message.EmailMessage`, per :rfc:`2046`, raise an error if a *cte* of ``quoted-printable`` or ``base64`` is requested for *subtype* ``rfc822``, and for any *cte* other than @@ -191,13 +197,6 @@ Currently the email package provides only one concrete content manager, (distinguished from strings by having a ``name`` attribute), add the headers to *msg*. - Note that this method will append a newline character to the end of strings, - if it wasn't passed already. For example, the following are equivalent :: - - msg = EmailMessage() - msg.set_content("hello") - msg.set_content("hello\n") - .. rubric:: Footnotes