gh-49680: Test exact APPEND and email message round-trip

Read the APPEND literal by its octet count and verify that a serialized
email message with bare LF is sent verbatim when translate_line_endings
is false.  Document using email.policy.SMTP for that case.

Co-authored-by: harjoth <harjoth.khara@gmail.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

Doc/library/imaplib.rst

@@ -208,6 +208,9 @@ An :class:`IMAP4` instance has the following methods:
    line endings in *message* are translated to CRLF.
    Pass ``False`` to send the message literal exactly as given,
    which is required to preserve messages that contain bare CR or LF.
+   In that case *message* must already use CRLF line endings as required
+   by :rfc:`3501`; for example, serialize :mod:`email` messages using
+   :class:`email.policy.SMTP`.
 
    .. versionchanged:: next
       Added the *translate_line_endings* parameter.

Lib/test/test_imaplib.py

@@ -2,13 +2,15 @@
 from test.support import socket_helper
 
 from contextlib import contextmanager
+from email.message import EmailMessage
 import imaplib
 import os.path
 import socketserver
 import time
 import calendar
 import threading
 import re
+import select
 import socket
 
 from test.support import verbose, run_with_tz, run_with_locale, cpython_only
@@ -27,6 +29,18 @@
 CAFILE = os.path.join(os.path.dirname(__file__) or os.curdir, "certdata", "pycacert.pem")
 
 
+def _read_literal(handler, marker):
+    # Read one literal, a raw octet sequence, by its count from the marker
+    # ('{N}', or '(~{N}' in UTF8 mode).
+    size = int(re.search(r'\{(\d+)\}', marker).group(1))
+    # The client must wait for the continuation, so nothing should be readable.
+    if select.select([handler.connection], [], [], 0)[0]:
+        raise AssertionError('client sent the literal before the '
+                             'continuation request')
+    handler._send_textline('+')
+    return handler.rfile.read(size)
+
+
 class TestImaplib(unittest.TestCase):
 
     def test_Internaldate2tuple(self):
@@ -371,10 +385,8 @@ def cmd_AUTHENTICATE(self, tag, args):
                 self.server.response = yield
                 self._send_tagged(tag, 'OK', 'FAKEAUTH successful')
             def cmd_APPEND(self, tag, args):
-                self._send_textline('+')
                 self.server.response = args
-                literal = yield
-                self.server.response.append(literal)
+                self.server.response.append(_read_literal(self, args[-1]))
                 literal = yield
                 self.server.response.append(literal)
                 self._send_tagged(tag, 'OK', 'okay')
@@ -635,24 +647,32 @@ def test_login(self):
         self.assertEqual(client.state, 'AUTH')
 
     def test_append_translate_line_endings(self):
-        # By default line endings in the message are normalized to CRLF;
-        # translate_line_endings=False sends the literal exactly (gh-49680).
+        # By default line endings are normalized to CRLF; False sends the
+        # literal exactly (gh-49680).
         class AppendHandler(SimpleIMAPHandler):
             def cmd_APPEND(self, tag, args):
-                size = int(args[-1].strip('{}'))
-                self._send_textline('+')
-                self.server.response = self.rfile.read(size)
-                self.rfile.readline()  # trailing CRLF after the literal
+                self.server.response = _read_literal(self, args[-1])
+                yield  # read the trailer line
                 self._send_tagged(tag, 'OK', 'APPEND completed')
-        message = b'a\rb\nc\r\nd'
         client, server = self._setup(AppendHandler)
         client.login('user', 'pass')
+        message = b'a\rb\nc\r\nd'
         client.append('INBOX', None, None, message)
         self.assertEqual(server.response, b'a\r\nb\r\nc\r\nd')
         client.append('INBOX', None, None, message,
                       translate_line_endings=False)
         self.assertEqual(server.response, message)
 
+        # An email message uses bare LF by default; False sends it verbatim.
+        message = EmailMessage()
+        message['Subject'] = 'line endings'
+        message.set_content('body line\n')
+        message = message.as_bytes()
+        self.assertNotIn(b'\r\n', message)
+        client.append('INBOX', None, None, message,
+                      translate_line_endings=False)
+        self.assertEqual(server.response, message)
+
     def test_logout(self):
         client, _ = self._setup(SimpleIMAPHandler)
         typ, data = client.login('user', 'pass')
@@ -944,10 +964,8 @@ def test_enable_UTF8_True_append(self):
 
         class UTF8AppendServer(self.UTF8Server):
             def cmd_APPEND(self, tag, args):
-                self._send_textline('+')
                 self.server.response = args
-                literal = yield
-                self.server.response.append(literal)
+                self.server.response.append(_read_literal(self, args[-1]))
                 literal = yield
                 self.server.response.append(literal)
                 self._send_tagged(tag, 'OK', 'okay')