IMAPClient 4.0.0__tar.gz → 4.1.0__tar.gz

{imapclient-4.0.0 → imapclient-4.1.0}/AUTHORS.rst

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

{imapclient-4.0.0 → imapclient-4.1.0/IMAPClient.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.0.0
+Version: 4.1.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>
@@ -28,7 +28,6 @@ IMAPClient is an easy-to-use, Pythonic and complete IMAP client
 library.
 
 =========================  ========================================
-Current version            3.0.1
 Supported Python versions  3.8 - 3.14
 License                    New BSD
 Project home               https://github.com/mjs/imapclient/

{imapclient-4.0.0 → imapclient-4.1.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.0/IMAPClient.egg-info → imapclient-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.0.0
+Version: 4.1.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>
@@ -28,7 +28,6 @@ IMAPClient is an easy-to-use, Pythonic and complete IMAP client
 library.
 
 =========================  ========================================
-Current version            3.0.1
 Supported Python versions  3.8 - 3.14
 License                    New BSD
 Project home               https://github.com/mjs/imapclient/

{imapclient-4.0.0 → imapclient-4.1.0}/README.rst

@@ -4,7 +4,6 @@ IMAPClient is an easy-to-use, Pythonic and complete IMAP client
 library.
 
 =========================  ========================================
-Current version            3.0.1
 Supported Python versions  3.8 - 3.14
 License                    New BSD
 Project home               https://github.com/mjs/imapclient/

{imapclient-4.0.0 → imapclient-4.1.0}/imapclient/imapclient.py

@@ -378,13 +378,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):

{imapclient-4.0.0 → imapclient-4.1.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.0 → imapclient-4.1.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "IMAPClient"
 description = "Easy-to-use, Pythonic and complete IMAP client library"
-version = "4.0.0"
+version = "4.1.0"
 authors = [
     {name = "Menno Finlay-Smits", email = "hello@menno.io"},
 ]

{imapclient-4.0.0 → imapclient-4.1.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.1.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.1.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()