From 29cb612796f04ea0697a974cf26e696ba0ecf638 Mon Sep 17 00:00:00 2001 From: Yizheng Meng Date: Thu, 18 Jul 2024 16:54:39 +0800 Subject: [PATCH] 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 bf917c84cdabf5a..f4d162fd967caab 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