#24277: The new email API is no longer provisional.

This is a wholesale reorganization and editing of the email documentation to
make the new API the standard one, and the old API the 'legacy' one.  The
default is still the compat32 policy, for backward compatibility.  We will
change that eventually.

2 files changed, 40 insertions, 0 deletions

diff --git a/Lib/email/message.py b/Lib/email/message.py
index 4b04283..c07da43 100644
--- a/Lib/email/message.py
+++ b/Lib/email/message.py
@@ -951,6 +951,26 @@ class MIMEPart(Message):
             policy = default
         Message.__init__(self, policy)
 
+
+    def as_string(self, unixfrom=False, maxheaderlen=None, policy=None):
+        """Return the entire formatted message as a string.
+
+        Optional 'unixfrom', when true, means include the Unix From_ envelope
+        header.  maxheaderlen is retained for backward compatibility with the
+        base Message class, but defaults to None, meaning that the policy value
+        for max_line_length controls the header maximum length.  'policy' is
+        passed to the Generator instance used to serialize the mesasge; if it
+        is not specified the policy associated with the message instance is
+        used.
+        """
+        policy = self.policy if policy is None else policy
+        if maxheaderlen is None:
+            maxheaderlen = policy.max_line_length
+        return super().as_string(maxheaderlen=maxheaderlen, policy=policy)
+
+    def __str__(self):
+        return self.as_string(policy=self.policy.clone(utf8=True))
+
     def is_attachment(self):
         c_d = self.get('content-disposition')
         return False if c_d is None else c_d.content_disposition == 'attachment'
diff --git a/Lib/test/test_email/test_message.py b/Lib/test/test_email/test_message.py
index 4345162..f3a57df 100644
--- a/Lib/test/test_email/test_message.py
+++ b/Lib/test/test_email/test_message.py
@@ -764,6 +764,26 @@ class TestEmailMessage(TestEmailMessageBase, TestEmailBase):
         m.set_content(content_manager=cm)
         self.assertEqual(m['MIME-Version'], '1.0')
 
+    def test_as_string_uses_max_header_length_by_default(self):
+        m = self._str_msg('Subject: long line' + ' ab'*50 + '\n\n')
+        self.assertEqual(len(m.as_string().strip().splitlines()), 3)
+
+    def test_as_string_allows_maxheaderlen(self):
+        m = self._str_msg('Subject: long line' + ' ab'*50 + '\n\n')
+        self.assertEqual(len(m.as_string(maxheaderlen=0).strip().splitlines()),
+                         1)
+        self.assertEqual(len(m.as_string(maxheaderlen=34).strip().splitlines()),
+                         6)
+
+    def test_str_defaults_to_policy_max_line_length(self):
+        m = self._str_msg('Subject: long line' + ' ab'*50 + '\n\n')
+        self.assertEqual(len(str(m).strip().splitlines()), 3)
+
+    def test_str_defaults_to_utf8(self):
+        m = EmailMessage()
+        m['Subject'] = 'unicöde'
+        self.assertEqual(str(m), 'Subject: unicöde\n\n')
+
 
 class TestMIMEPart(TestEmailMessageBase, TestEmailBase):
     # Doing the full test run here may seem a bit redundant, since the two