IMAPClient 4.1.0__tar.gz → 4.2.0__tar.gz

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

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.1.0
+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.1.0/IMAPClient.egg-info → imapclient-4.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: IMAPClient
-Version: 4.1.0
+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.1.0 → 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):
@@ -1461,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())
 
@@ -1709,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:
@@ -1872,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
@@ -1883,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
@@ -1979,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.1.0 → 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.1.0"
+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.1.0 → 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.1.0 → 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.1.0 → 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"])