IMAPClient 4.0.1__tar.gz → 4.2.0__tar.gz

{imapclient-4.0.1 → imapclient-4.2.0}/AUTHORS.rst

@@ -48,4 +48,4 @@ project:
 - Sean Whalen
 - Peter Wienemann 
 - Arnout Engelen
-
+- Lars Artmann

{imapclient-4.0.1 → imapclient-4.2.0/IMAPClient.egg-info}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.0.1
+Version: 4.2.0
 Summary: Easy-to-use, Pythonic and complete IMAP client library
 Author-email: Menno Finlay-Smits <hello@menno.io>
 Maintainer-email: IMAPClient Maintainers <imapclient@groups.io>
+License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mjs/imapclient/
 Keywords: imap,client,email,mail
 Classifier: Development Status :: 5 - Production/Stable

{imapclient-4.0.1 → imapclient-4.2.0}/IMAPClient.egg-info/SOURCES.txt

@@ -38,6 +38,8 @@ tests/test_response_parser.py
 tests/test_search.py
 tests/test_sort.py
 tests/test_starttls.py
+tests/test_starttls_integration.py
 tests/test_store.py
 tests/test_thread.py
+tests/test_tls_integration.py
 tests/test_util_functions.py

{imapclient-4.0.1/IMAPClient.egg-info → imapclient-4.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.0.1
+Version: 4.2.0
 Summary: Easy-to-use, Pythonic and complete IMAP client library
 Author-email: Menno Finlay-Smits <hello@menno.io>
 Maintainer-email: IMAPClient Maintainers <imapclient@groups.io>
+License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mjs/imapclient/
 Keywords: imap,client,email,mail
 Classifier: Development Status :: 5 - Production/Stable

{imapclient-4.0.1 → imapclient-4.2.0}/imapclient/imapclient.py

@@ -42,6 +42,7 @@ __all__ = [
     "FLAGGED",
     "DRAFT",
     "RECENT",
+    "literal",
 ]
 
 
@@ -321,6 +322,21 @@ class IMAPClient:
 
         connect_timeout = getattr(self._timeout, "connect", None)
 
+        if sys.version_info < (3, 9):
+            # Support for Python 3.8
+            if connect_timeout:
+                raise ValueError(
+                    "connection timeout is not supported with this version of Python"
+                )
+
+            if self.ssl:
+                return tls.IMAP4_TLS(
+                    self.host,
+                    self.port,
+                    self.ssl_context,
+                )
+            return imap4.IMAP4WithTimeout(self.host, self.port)
+
         if self.ssl:
             return tls.IMAP4_TLS(
                 self.host,
@@ -328,7 +344,6 @@ class IMAPClient:
                 self.ssl_context,
                 connect_timeout,
             )
-
         return imap4.IMAP4WithTimeout(self.host, self.port, connect_timeout)
 
     def _set_read_timeout(self):
@@ -378,13 +393,17 @@ class IMAPClient:
         if self.ssl or self._starttls_done:
             raise exceptions.IMAPClientAbortError("TLS session already established")
 
-        typ, data = self._imap._simple_command("STARTTLS")
+        # Delegate the socket wrap to imaplib: it manages its own read buffer
+        # since Python 3.14 (where IMAP4.file became a read-only property).
+        # imaplib's own None-fallback context does not verify certificates, so
+        # pass IMAPClient's verifying default instead.
+        if ssl_context is None:
+            ssl_context = tls.create_default_context()
+
+        typ, data = self._imap.starttls(ssl_context=ssl_context)
         self._checkok("starttls", typ, data)
 
         self._starttls_done = True
-
-        self._imap.sock = tls.wrap_socket(self._imap.sock, ssl_context, self.host)
-        self._imap.file = self._imap.sock.makefile("rb")
         return data[0]
 
     def login(self, username: str, password: str):
@@ -1457,9 +1476,9 @@ class IMAPClient:
                         yield to_bytes(seq_to_parenstr(m["flags"]))
                     if "date" in m:
                         yield to_bytes('"%s"' % datetime_to_INTERNALDATE(m["date"]))
-                    yield _literal(to_bytes(m["msg"]))
+                    yield literal(to_bytes(m["msg"]))
                 else:
-                    yield _literal(to_bytes(m))
+                    yield literal(to_bytes(m))
 
         msgs = list(chunks())
 
@@ -1705,11 +1724,25 @@ class IMAPClient:
             prefix.append(b"UID")
         prefix.append(command)
 
-        line = []
-        for item, is_last in _iter_with_last(prefix + args):
+        # Check every argument before anything goes on the wire: a bad
+        # argument found after a literal was sent would leave the server
+        # waiting inside a half-sent command.
+        for item in itertools.chain(prefix, args):
             if not isinstance(item, bytes):
                 raise ValueError("command args must be passed as bytes")
+            if b"\x00" in item:
+                raise ValueError("NUL is not allowed in command arguments")
+            if not _is8bit(item) and (b"\r" in item or b"\n" in item):
+                # CR and LF end the command line on the wire, so an argument
+                # carrying them would be run as extra commands. A literal can
+                # hold them, which is what the 8-bit path already sends.
+                raise ValueError(
+                    "CR and LF are not allowed in command arguments; "
+                    "wrap the value in imapclient.literal to send it as a literal"
+                )
 
+        line = []
+        for item, is_last in _iter_with_last(prefix + args):
             if _is8bit(item):
                 # If a line was already started send it
                 if line:
@@ -1868,6 +1901,8 @@ def _normalise_search_criteria(criteria, charset=None):
             inner[0] = b"(" + inner[0]
             inner[-1] = inner[-1] + b")"
             out.extend(inner)  # flatten
+        elif isinstance(item, literal):
+            out.append(item)
         else:
             out.append(_quoted.maybe(to_bytes(item, charset)))
     return out
@@ -1879,10 +1914,13 @@ def _normalise_sort_criteria(criteria, charset=None):
     return b"(" + b" ".join(to_bytes(item).upper() for item in criteria) + b")"
 
 
-class _literal(bytes):
+class literal(bytes):
     """Hold message data that should always be sent as a literal."""
 
 
+_literal = literal  # old private name, kept for callers that imported it
+
+
 class _quoted(bytes):
     """
     This class holds a quoted bytes value which provides access to the
@@ -1975,7 +2013,7 @@ def as_triplets(items):
 
 
 def _is8bit(data):
-    return isinstance(data, _literal) or any(b > 127 for b in data)
+    return isinstance(data, literal) or any(b > 127 for b in data)
 
 
 def _iter_with_last(items):

{imapclient-4.0.1 → imapclient-4.2.0}/imapclient/tls.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2023, Menno Smits
+# Copyright (c) 2026, Menno Smits
 # Released subject to the New BSD License
 # Please see http://en.wikipedia.org/wiki/BSD_licenses
 
@@ -13,11 +13,15 @@ import ssl
 from typing import Optional
 
 
+def create_default_context() -> ssl.SSLContext:
+    return ssl.create_default_context(purpose=ssl.Purpose.SERVER_AUTH)
+
+
 def wrap_socket(
     sock: socket.socket, ssl_context: Optional[ssl.SSLContext], host: str
 ) -> socket.socket:
     if ssl_context is None:
-        ssl_context = ssl.create_default_context(purpose=ssl.Purpose.SERVER_AUTH)
+        ssl_context = create_default_context()
 
     return ssl_context.wrap_socket(sock, server_hostname=host)
 
@@ -39,7 +43,9 @@ class IMAP4_TLS(imaplib.IMAP4):
         self._timeout = timeout
         super().__init__(host, port)
 
-    def _create_socket(self, timeout: Optional[float]) -> socket.socket:
+    def _create_socket(self, timeout: Optional[float] = None) -> socket.socket:
+        if timeout is None:
+            timeout = self._timeout
         sock = socket.create_connection((self.host, self.port), timeout=timeout)
 
         return wrap_socket(sock, self.ssl_context, self.host)

{imapclient-4.0.1 → imapclient-4.2.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "IMAPClient"
 description = "Easy-to-use, Pythonic and complete IMAP client library"
-version = "4.0.1"
+version = "4.2.0"
+license = {text = "BSD-3-Clause"}
 authors = [
     {name = "Menno Finlay-Smits", email = "hello@menno.io"},
 ]
@@ -46,6 +47,7 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
+license-files = ["COPYING", "AUTHORS.rst"]
 packages = ["imapclient"]
 
 [tool.setuptools.package-data]

{imapclient-4.0.1 → imapclient-4.2.0}/tests/test_imapclient.py

@@ -15,18 +15,59 @@ from unittest.mock import Mock, patch, sentinel
 from imapclient.exceptions import CapabilityError, IMAPClientError, ProtocolError
 from imapclient.fixed_offset import FixedOffset
 from imapclient.imapclient import (
-    _literal,
     _parse_quota,
+)
+from imapclient.imapclient import IMAPClient as RealIMAPClient
+from imapclient.imapclient import (
     IMAPlibLoggerAdapter,
+    literal,
     MailboxQuotaRoots,
     Quota,
     require_capability,
+    SocketTimeout,
 )
 from imapclient.testable_imapclient import TestableIMAPClient as IMAPClient
 
 from .imapclient_test import IMAPClientTest
 
 
+class TestCreateIMAP4(IMAPClientTest):
+    @patch("imapclient.imapclient.sys.version_info", (3, 8, 0))
+    @patch("imapclient.imapclient.tls.IMAP4_TLS")
+    @patch("imapclient.imapclient.imap4.IMAP4WithTimeout")
+    def test_python_38_does_not_pass_connect_timeout(self, plain_imap, tls_imap):
+        self.client._timeout = SocketTimeout(None, 30)
+        self.client.ssl_context = sentinel.ssl_context
+
+        self.client.ssl = True
+        self.assertIs(RealIMAPClient._create_IMAP4(self.client), tls_imap.return_value)
+        tls_imap.assert_called_once_with("somehost", 993, sentinel.ssl_context)
+        plain_imap.assert_not_called()
+
+        self.client.ssl = False
+        self.assertIs(
+            RealIMAPClient._create_IMAP4(self.client), plain_imap.return_value
+        )
+        plain_imap.assert_called_once_with("somehost", 993)
+
+    @patch("imapclient.imapclient.sys.version_info", (3, 8, 0))
+    @patch("imapclient.imapclient.tls.IMAP4_TLS")
+    @patch("imapclient.imapclient.imap4.IMAP4WithTimeout")
+    def test_python_38_rejects_connect_timeout(self, plain_imap, tls_imap):
+        self.client._timeout = SocketTimeout(10, 30)
+
+        for use_ssl in (True, False):
+            with self.subTest(ssl=use_ssl):
+                self.client.ssl = use_ssl
+                with self.assertRaisesRegex(
+                    ValueError, "connection timeout is not supported"
+                ):
+                    RealIMAPClient._create_IMAP4(self.client)
+
+        tls_imap.assert_not_called()
+        plain_imap.assert_not_called()
+
+
 class TestListFolders(IMAPClientTest):
     def test_list_folders(self):
         self.client._imap._simple_command.return_value = ("OK", [b"something"])
@@ -416,11 +457,11 @@ class TestAppend(IMAPClientTest):
                 b'"foobar"',
                 b"(FLAG WAVE)",
                 b'"05-Apr-2009 11:00:05 +0200"',
-                _literal(b"msg1"),
+                literal(b"msg1"),
                 b"(FLAG WAVE)",
-                _literal(b"msg2"),
+                literal(b"msg2"),
                 b'"05-Apr-2009 11:00:05 +0200"',
-                _literal(b"msg3"),
+                literal(b"msg3"),
             ],
             uid=False,
         )
@@ -749,6 +790,40 @@ class TestIdleAndNoop(IMAPClientTest):
         self.assertListEqual([(99, b"EXISTS")], responses)
 
 
+class TestRawCommandRejectsControlCharacters(IMAPClientTest):
+    def setUp(self):
+        super().setUp()
+        self.client._imap.send = Mock()
+        self.client._cached_capabilities = (b"IMAP4REV1",)
+
+    def test_crlf_in_a_line_argument_is_rejected_before_sending(self):
+        criterion = b'x"\r\nX1 STORE 1:* +FLAGS (\\Deleted)\r\nX2 EXPUNGE'
+
+        with self.assertRaises(ValueError):
+            self.client._raw_command(b"SEARCH", [b"HEADER", b"Message-ID", criterion])
+
+        self.client._imap.send.assert_not_called()
+
+    def test_crlf_via_search_criteria_is_rejected_before_sending(self):
+        with self.assertRaises(ValueError):
+            self.client.search(["HEADER", "Message-ID", 'x"\r\nX1 NOOP'])
+
+        self.client._imap.send.assert_not_called()
+
+    def test_nul_is_rejected_even_inside_a_literal(self):
+        with self.assertRaises(ValueError):
+            self.client._raw_command(b"SEARCH", [b"TEXT", literal(b"a\x00b")])
+
+        self.client._imap.send.assert_not_called()
+
+    def test_crlf_inside_a_literal_is_allowed(self):
+        self.client._send_literal = Mock()
+
+        self.client._raw_command(b"SEARCH", [b"TEXT", literal(b"line one\r\nline two")])
+
+        self.client._send_literal.assert_called_once()
+
+
 class TestDebugLogging(IMAPClientTest):
     def test_IMAP_is_patched(self):
         # Remove all logging handlers so that the order of tests does not
@@ -1006,7 +1081,7 @@ class TestRawCommand(IMAPClientTest):
         self.client._cached_capabilities = (b"LITERAL+",)
 
         typ, data = self.client._raw_command(
-            b"APPEND", [b"\xff", _literal(b"hello")], uid=False
+            b"APPEND", [b"\xff", literal(b"hello")], uid=False
         )
         self.assertEqual(typ, "OK")
         self.assertEqual(data, ["done"])
@@ -1020,7 +1095,7 @@ class TestRawCommand(IMAPClientTest):
 
         typ, data = self.client._raw_command(
             b"APPEND",
-            [b"\xff", _literal(b"hello"), b"TEXT", _literal(b"test")],
+            [b"\xff", literal(b"hello"), b"TEXT", literal(b"test")],
             uid=False,
         )
         self.assertEqual(typ, "OK")

{imapclient-4.0.1 → imapclient-4.2.0}/tests/test_init.py

@@ -2,6 +2,7 @@
 # Released subject to the New BSD License
 # Please see http://en.wikipedia.org/wiki/BSD_licenses
 
+import sys
 import unittest
 from unittest.mock import Mock, patch, sentinel
 
@@ -22,6 +23,9 @@ class TestInit(unittest.TestCase):
         self.imaplib = patcher.start()
         self.addCleanup(patcher.stop)
 
+    @unittest.skipIf(
+        sys.version_info < (3, 9), "connection timeouts require Python 3.9+"
+    )
     def test_plain(self):
         fakeIMAP4 = Mock()
         self.imap4.IMAP4WithTimeout.return_value = fakeIMAP4
@@ -36,6 +40,9 @@ class TestInit(unittest.TestCase):
         self.assertEqual(imap.ssl_context, None)
         self.assertEqual(imap.stream, False)
 
+    @unittest.skipIf(
+        sys.version_info < (3, 9), "connection timeouts require Python 3.9+"
+    )
     def test_plain_SocketTimeout(self):
         fakeIMAP4 = Mock()
         self.imap4.IMAP4WithTimeout.return_value = fakeIMAP4
@@ -51,6 +58,9 @@ class TestInit(unittest.TestCase):
             "1.2.3.4", 143, sentinel.connect_timeout
         )
 
+    @unittest.skipIf(
+        sys.version_info < (3, 9), "connection timeouts require Python 3.9+"
+    )
     def test_SSL(self):
         fakeIMAP4_TLS = Mock()
         self.tls.IMAP4_TLS.return_value = fakeIMAP4_TLS
@@ -69,6 +79,9 @@ class TestInit(unittest.TestCase):
         self.assertEqual(imap.ssl_context, sentinel.context)
         self.assertEqual(imap.stream, False)
 
+    @unittest.skipIf(
+        sys.version_info < (3, 9), "connection timeouts require Python 3.9+"
+    )
     def test_SSL_SocketTimeout(self):
         fakeIMAP4_TLS = Mock()
         self.tls.IMAP4_TLS.return_value = fakeIMAP4_TLS

{imapclient-4.0.1 → imapclient-4.2.0}/tests/test_starttls.py

@@ -2,7 +2,7 @@
 # Released subject to the New BSD License
 # Please see http://en.wikipedia.org/wiki/BSD_licenses
 
-from unittest.mock import Mock, patch, sentinel
+from unittest.mock import patch, sentinel
 
 from imapclient.exceptions import IMAPClientError
 from imapclient.imapclient import IMAPClient
@@ -18,34 +18,31 @@ class TestStarttls(IMAPClientTest):
         self.tls = patcher.start()
         self.addCleanup(patcher.stop)
 
-        self.client._imap.sock = sentinel.old_sock
-
-        self.new_sock = Mock()
-        self.new_sock.makefile.return_value = sentinel.file
-        self.tls.wrap_socket.return_value = self.new_sock
-
-        self.client.host = sentinel.host
         self.client.ssl = False
         self.client._starttls_done = False
-        self.client._imap._simple_command.return_value = "OK", [
-            b"start TLS negotiation"
-        ]
+        self.client._imap.starttls.return_value = "OK", [b"start TLS negotiation"]
         self.client._cached_capabilities = [b"STARTTLS"]
 
     def test_works(self):
         resp = self.client.starttls(sentinel.ssl_context)
 
-        self.tls.wrap_socket.assert_called_once_with(
-            sentinel.old_sock,
-            sentinel.ssl_context,
-            sentinel.host,
+        self.client._imap.starttls.assert_called_once_with(
+            ssl_context=sentinel.ssl_context
+        )
+        self.tls.create_default_context.assert_not_called()
+        self.assertTrue(self.client._starttls_done)
+        self.assertEqual(resp, b"start TLS negotiation")
+
+    def test_default_context_is_used(self):
+        resp = self.client.starttls()
+
+        self.client._imap.starttls.assert_called_once_with(
+            ssl_context=self.tls.create_default_context.return_value
         )
-        self.new_sock.makefile.assert_called_once_with("rb")
-        self.assertEqual(self.client._imap.file, sentinel.file)
         self.assertEqual(resp, b"start TLS negotiation")
 
     def test_command_fails(self):
-        self.client._imap._simple_command.return_value = "NO", [b"sorry"]
+        self.client._imap.starttls.return_value = "NO", [b"sorry"]
 
         with self.assertRaises(IMAPClientError) as raised:
             self.client.starttls(sentinel.ssl_context)

imapclient-4.2.0/tests/test_starttls_integration.py

@@ -0,0 +1,162 @@
+# Copyright (c) 2025, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+"""Integration tests for starttls() over a real socket pair.
+
+These exercise the actual imaplib starttls code path (socket wrap plus
+read-buffer refresh), which unit tests with mocked IMAP4 objects cannot
+cover. This is the path that broke on Python 3.14, where IMAP4.file
+became a read-only property.
+"""
+
+import os
+import socket
+import ssl
+import sys
+import threading
+import unittest
+from pathlib import Path
+
+from imapclient.exceptions import IMAPClientError
+from imapclient.imapclient import IMAPClient
+
+CERT_DIR = Path(__file__).parent / "certs"
+CA_FILE = CERT_DIR / "ca.pem"
+SERVER_CERT = CERT_DIR / "server.pem"
+SERVER_KEY = CERT_DIR / "server.key"
+
+PRE_TLS_CAPS = b"IMAP4rev1 STARTTLS AUTH=PLAIN"
+POST_TLS_CAPS = b"IMAP4rev1 AUTH=PLAIN"
+
+
+class FakeSTARTTLSServer:
+    """Minimal IMAP4 server that upgrades to TLS when told STARTTLS.
+
+    Serves one connection per instance. Post-TLS CAPABILITY responses omit
+    STARTTLS, mirroring what real servers advertise once the connection is
+    secured.
+    """
+
+    def __init__(self):
+        self.refuse_tls = False
+        self.error = None
+        self.ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        self.ctx.load_cert_chain(str(SERVER_CERT), str(SERVER_KEY))
+        self.sock = socket.socket()
+        self.sock.bind(("127.0.0.1", 0))
+        self.sock.listen(1)
+        self.port = self.sock.getsockname()[1]
+        self.thread = threading.Thread(target=self._serve, daemon=True)
+        self.thread.start()
+
+    def _reply_caps(self, conn, tag, caps):
+        conn.sendall(b"* CAPABILITY " + caps + b"\r\n")
+        conn.sendall(tag + b" OK CAPABILITY completed\r\n")
+
+    def _serve(self):
+        try:
+            conn, _ = self.sock.accept()
+            conn.sendall(
+                b"* OK [CAPABILITY " + PRE_TLS_CAPS + b"] fake server ready\r\n"
+            )
+            f = conn.makefile("rb")
+            while True:
+                line = f.readline()
+                if not line:
+                    break
+                parts = line.split(None, 1)
+                tag = parts[0]
+                cmd = parts[1].strip().upper() if len(parts) > 1 else b""
+                if cmd.startswith(b"CAPABILITY"):
+                    self._reply_caps(conn, tag, PRE_TLS_CAPS)
+                elif cmd.startswith(b"STARTTLS"):
+                    if self.refuse_tls:
+                        conn.sendall(tag + b" NO TLS refused\r\n")
+                        continue
+                    conn.sendall(tag + b" OK Begin TLS now\r\n")
+                    self._serve_tls(self.ctx.wrap_socket(conn, server_side=True))
+                    return
+                elif cmd.startswith(b"LOGOUT"):
+                    conn.sendall(b"* BYE fake server signing off\r\n")
+                    conn.sendall(tag + b" OK LOGOUT completed\r\n")
+                    conn.close()
+                    return
+                else:
+                    conn.sendall(tag + b" OK done\r\n")
+        except Exception as e:
+            self.error = e
+
+    def _serve_tls(self, conn):
+        f = conn.makefile("rb")
+        while True:
+            line = f.readline()
+            if not line:
+                break
+            parts = line.split(None, 1)
+            tag = parts[0]
+            cmd = parts[1].strip().upper() if len(parts) > 1 else b""
+            if cmd.startswith(b"CAPABILITY"):
+                self._reply_caps(conn, tag, POST_TLS_CAPS)
+            elif cmd.startswith(b"LOGOUT"):
+                conn.sendall(b"* BYE fake server signing off\r\n")
+                conn.sendall(tag + b" OK LOGOUT completed\r\n")
+                conn.close()
+                return
+            else:
+                conn.sendall(tag + b" OK done\r\n")
+
+
+@unittest.skipIf(
+    sys.version_info < (3, 9),
+    "imaplib.IMAP4 gained the timeout parameter in Python 3.9",
+)
+class StarttlsSocketTests(unittest.TestCase):
+    def setUp(self):
+        self.server = FakeSTARTTLSServer()
+        self._saved_cert_file = os.environ.pop("SSL_CERT_FILE", None)
+        os.environ["SSL_CERT_FILE"] = str(CA_FILE)
+
+    def tearDown(self):
+        if self._saved_cert_file is not None:
+            os.environ["SSL_CERT_FILE"] = self._saved_cert_file
+        self.server.sock.close()
+        self.assertIsNone(self.server.error)
+
+    def _client(self):
+        return IMAPClient("localhost", self.server.port, ssl=False)
+
+    def test_starttls_with_default_context(self):
+        client = self._client()
+
+        client.starttls()
+
+        sock = client._imap.sock
+        self.assertIsInstance(sock, ssl.SSLSocket)
+        # IMAPClient's documented default: hostname checking and certificate
+        # verification ON. imaplib's own None-fallback is unverified.
+        self.assertTrue(sock.context.check_hostname)
+        self.assertEqual(sock.context.verify_mode, ssl.CERT_REQUIRED)
+
+        self.assertNotIn(b"STARTTLS", client.capabilities())
+        client.login("user", "pass")
+        client.logout()
+
+    def test_starttls_with_custom_context(self):
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+
+        client = self._client()
+        client.starttls(context)
+
+        self.assertIs(client._imap.sock.context, context)
+        client.login("user", "pass")
+        client.logout()
+
+    def test_starttls_refused_raises_imapclient_error(self):
+        self.server.refuse_tls = True
+        client = self._client()
+
+        with self.assertRaises(IMAPClientError):
+            client.starttls()

imapclient-4.2.0/tests/test_tls_integration.py

@@ -0,0 +1,133 @@
+# Copyright (c) 2025, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+"""Integration tests for IMAPClient(..., ssl=True) over a real socket pair.
+
+These exercise the actual TLS-from-connect code path (tls.IMAP4_TLS socket
+wrap), which unit tests with mocked IMAP4 objects cannot cover. They mirror
+tests/test_starttls_integration.py, but with TLS established at connection
+time instead of via the STARTTLS command.
+"""
+
+import os
+import socket
+import ssl
+import sys
+import threading
+import unittest
+from pathlib import Path
+
+from imapclient.imapclient import IMAPClient
+
+CERT_DIR = Path(__file__).parent / "certs"
+CA_FILE = CERT_DIR / "ca.pem"
+SERVER_CERT = CERT_DIR / "server.pem"
+SERVER_KEY = CERT_DIR / "server.key"
+
+CAPS = b"IMAP4rev1 AUTH=PLAIN"
+
+
+class FakeTLSServer:
+    """Minimal IMAP4 server that speaks TLS from the moment it accepts.
+
+    Serves one connection per instance. TLS handshake failures (expected
+    when the client rejects the server certificate) are recorded in
+    tls_error rather than error so tearDown can ignore them.
+    """
+
+    def __init__(self):
+        self.error = None
+        self.tls_error = None
+        self.ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        self.ctx.load_cert_chain(str(SERVER_CERT), str(SERVER_KEY))
+        self.sock = socket.socket()
+        self.sock.bind(("127.0.0.1", 0))
+        self.sock.listen(1)
+        self.port = self.sock.getsockname()[1]
+        self.thread = threading.Thread(target=self._serve, daemon=True)
+        self.thread.start()
+
+    def _serve(self):
+        try:
+            conn, _ = self.sock.accept()
+            try:
+                conn = self.ctx.wrap_socket(conn, server_side=True)
+            except ssl.SSLError as e:
+                self.tls_error = e
+                conn.close()
+                return
+            conn.sendall(b"* OK [CAPABILITY " + CAPS + b"] fake server ready\r\n")
+            f = conn.makefile("rb")
+            while True:
+                line = f.readline()
+                if not line:
+                    break
+                parts = line.split(None, 1)
+                tag = parts[0]
+                cmd = parts[1].strip().upper() if len(parts) > 1 else b""
+                if cmd.startswith(b"CAPABILITY"):
+                    conn.sendall(b"* CAPABILITY " + CAPS + b"\r\n")
+                    conn.sendall(tag + b" OK CAPABILITY completed\r\n")
+                elif cmd.startswith(b"LOGOUT"):
+                    conn.sendall(b"* BYE fake server signing off\r\n")
+                    conn.sendall(tag + b" OK LOGOUT completed\r\n")
+                    conn.close()
+                    return
+                else:
+                    conn.sendall(tag + b" OK done\r\n")
+        except Exception as e:
+            self.error = e
+
+
+@unittest.skipIf(
+    sys.version_info < (3, 9),
+    "imaplib.IMAP4 gained the timeout parameter in Python 3.9",
+)
+class TlsSocketTests(unittest.TestCase):
+    def setUp(self):
+        self.server = FakeTLSServer()
+        self._saved_cert_file = os.environ.pop("SSL_CERT_FILE", None)
+        os.environ["SSL_CERT_FILE"] = str(CA_FILE)
+
+    def tearDown(self):
+        if self._saved_cert_file is not None:
+            os.environ["SSL_CERT_FILE"] = self._saved_cert_file
+        self.server.sock.close()
+        self.assertIsNone(self.server.error)
+
+    def _client(self, **kwargs):
+        return IMAPClient("localhost", self.server.port, ssl=True, **kwargs)
+
+    def test_ssl_connect_with_default_context(self):
+        client = self._client()
+
+        sock = client._imap.sock
+        self.assertIsInstance(sock, ssl.SSLSocket)
+        # IMAPClient's documented default: hostname checking and certificate
+        # verification ON. imaplib's own None-fallback is unverified.
+        self.assertTrue(sock.context.check_hostname)
+        self.assertEqual(sock.context.verify_mode, ssl.CERT_REQUIRED)
+
+        self.assertIn(b"IMAP4REV1", client.capabilities())
+        client.login("user", "pass")
+        client.logout()
+
+    def test_ssl_connect_with_custom_context(self):
+        context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+
+        client = self._client(ssl_context=context)
+
+        self.assertIs(client._imap.sock.context, context)
+        client.login("user", "pass")
+        client.logout()
+
+    def test_ssl_connect_untrusted_cert_fails(self):
+        # Without the test CA in the verification path, the default context
+        # must reject the server's self-signed certificate.
+        del os.environ["SSL_CERT_FILE"]
+
+        with self.assertRaises(ssl.SSLError):
+            self._client()

{imapclient-4.0.1 → imapclient-4.2.0}/tests/test_util_functions.py

@@ -9,6 +9,7 @@ from imapclient.imapclient import (
     _normalise_search_criteria,
     _quoted,
     join_message_ids,
+    literal,
     normalise_text_list,
     seq_to_parenstr,
     seq_to_parenstr_upper,
@@ -139,6 +140,10 @@ class Test_normalise_search_criteria(unittest.TestCase):
     def test_quoting(self):
         self.check(["foo bar"], None, [_quoted(b'"foo bar"')])
 
+    def test_literal_is_not_quoted(self):
+        value = literal(b"line one\r\nline two")
+        self.check(["TEXT", value], None, [b"TEXT", value])
+
     def test_ints(self):
         self.check(["modseq", 500], None, [b"modseq", b"500"])