IMAPClient 4.0.0__py3-none-any.whl

imapclient/response_lexer.py

@@ -0,0 +1,174 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+"""
+A lexical analyzer class for IMAP responses.
+
+Although Lexer does all the work, TokenSource is the class to use for
+external callers.
+"""
+
+from typing import Iterator, List, Optional, Tuple, TYPE_CHECKING, Union
+
+from .util import assert_imap_protocol
+
+__all__ = ["TokenSource"]
+
+CTRL_CHARS = frozenset(c for c in range(32))
+ALL_CHARS = frozenset(c for c in range(256))
+SPECIALS = frozenset(c for c in b' ()%"[')
+NON_SPECIALS = ALL_CHARS - SPECIALS - CTRL_CHARS
+WHITESPACE = frozenset(c for c in b" \t\r\n")
+
+BACKSLASH = ord("\\")
+OPEN_SQUARE = ord("[")
+CLOSE_SQUARE = ord("]")
+DOUBLE_QUOTE = ord('"')
+
+
+class TokenSource:
+    """
+    A simple iterator for the Lexer class that also provides access to
+    the current IMAP literal.
+    """
+
+    def __init__(self, text: List[bytes]):
+        self.lex = Lexer(text)
+        self.src = iter(self.lex)
+
+    @property
+    def current_literal(self) -> Optional[bytes]:
+        if TYPE_CHECKING:
+            assert self.lex.current_source is not None
+        return self.lex.current_source.literal
+
+    def __iter__(self) -> Iterator[bytes]:
+        return self.src
+
+
+class Lexer:
+    """
+    A lexical analyzer class for IMAP
+    """
+
+    def __init__(self, text: List[bytes]):
+        self.sources = (LiteralHandlingIter(chunk) for chunk in text)
+        self.current_source: Optional[LiteralHandlingIter] = None
+
+    def read_until(
+        self, stream_i: "PushableIterator", end_char: int, escape: bool = True
+    ) -> bytearray:
+        token = bytearray()
+        try:
+            for nextchar in stream_i:
+                if escape and nextchar == BACKSLASH:
+                    escaper = nextchar
+                    nextchar = next(stream_i)
+                    if nextchar not in (escaper, end_char):
+                        token.append(escaper)  # Don't touch invalid escaping
+                elif nextchar == end_char:
+                    break
+                token.append(nextchar)
+            else:
+                raise ValueError("No closing '%s'" % chr(end_char))
+        except StopIteration:
+            raise ValueError("No closing '%s'" % chr(end_char))
+        token.append(end_char)
+        return token
+
+    def read_token_stream(self, stream_i: "PushableIterator") -> Iterator[bytearray]:
+        whitespace = WHITESPACE
+        wordchars = NON_SPECIALS
+        read_until = self.read_until
+
+        while True:
+            # Whitespace
+            for nextchar in stream_i:
+                if nextchar not in whitespace:
+                    stream_i.push(nextchar)
+                    break  # done skipping over the whitespace
+
+            # Non-whitespace
+            token = bytearray()
+            for nextchar in stream_i:
+                if nextchar in wordchars:
+                    token.append(nextchar)
+                elif nextchar == OPEN_SQUARE:
+                    token.append(nextchar)
+                    token.extend(read_until(stream_i, CLOSE_SQUARE, escape=False))
+                else:
+                    if nextchar in whitespace:
+                        yield token
+                    elif nextchar == DOUBLE_QUOTE:
+                        assert_imap_protocol(not token)
+                        token.append(nextchar)
+                        token.extend(read_until(stream_i, nextchar))
+                        yield token
+                    else:
+                        # Other punctuation, eg. "(". This ends the current token.
+                        if token:
+                            yield token
+                        yield bytearray([nextchar])
+                    break
+            else:
+                if token:
+                    yield token
+                break
+
+    def __iter__(self) -> Iterator[bytes]:
+        for source in self.sources:
+            self.current_source = source
+            for tok in self.read_token_stream(iter(source)):
+                yield bytes(tok)
+
+
+# imaplib has poor handling of 'literals' - it both fails to remove the
+# {size} marker, and fails to keep responses grouped into the same logical
+# 'line'.  What we end up with is a list of response 'records', where each
+# record is either a simple string, or tuple of (str_with_lit, literal) -
+# where str_with_lit is a string with the {xxx} marker at its end.  Note
+# that each element of this list does *not* correspond 1:1 with the
+# untagged responses.
+# (http://bugs.python.org/issue5045 also has comments about this)
+# So: we have a special object for each of these records.  When a
+# string literal is processed, we peek into this object to grab the
+# literal.
+class LiteralHandlingIter:
+    def __init__(self, resp_record: Union[Tuple[bytes, bytes], bytes]):
+        self.literal: Optional[bytes]
+        if isinstance(resp_record, tuple):
+            # A 'record' with a string which includes a literal marker, and
+            # the literal itself.
+            self.src_text = resp_record[0]
+            assert_imap_protocol(self.src_text.endswith(b"}"), self.src_text)
+            self.literal = resp_record[1]
+        else:
+            # just a line with no literals.
+            self.src_text = resp_record
+            self.literal = None
+
+    def __iter__(self) -> "PushableIterator":
+        return PushableIterator(self.src_text)
+
+
+class PushableIterator:
+    NO_MORE = object()
+
+    def __init__(self, it: bytes):
+        self.it = iter(it)
+        self.pushed: List[int] = []
+
+    def __iter__(self) -> "PushableIterator":
+        return self
+
+    def __next__(self) -> int:
+        if self.pushed:
+            return self.pushed.pop()
+        return next(self.it)
+
+    # For Python 2 compatibility
+    next = __next__
+
+    def push(self, item: int) -> None:
+        self.pushed.append(item)

imapclient/response_parser.py

@@ -0,0 +1,287 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+"""
+Parsing for IMAP command responses with focus on FETCH responses as
+returned by imaplib.
+
+Initially inspired by http://effbot.org/zone/simple-iterator-parser.htm
+"""
+
+# TODO more exact error reporting
+
+import datetime
+import re
+import sys
+from collections import defaultdict
+from typing import cast, Dict, Iterator, List, Optional, Tuple, TYPE_CHECKING, Union
+
+from .datetime_util import parse_to_datetime
+from .exceptions import ProtocolError
+from .response_lexer import TokenSource
+from .response_types import Address, BodyData, Envelope, SearchIds
+from .typing_imapclient import _Atom
+
+__all__ = ["parse_response", "parse_message_list"]
+
+
+def parse_response(data: List[bytes]) -> Tuple[_Atom, ...]:
+    """Pull apart IMAP command responses.
+
+    Returns nested tuples of appropriately typed objects.
+    """
+    if data == [None]:
+        return tuple()
+    return tuple(gen_parsed_response(data))
+
+
+_msg_id_pattern = re.compile(r"(\d+(?: +\d+)*)")
+
+
+def parse_message_list(data: List[Union[bytes, str]]) -> SearchIds:
+    """Parse a list of message ids and return them as a list.
+
+    parse_response is also capable of doing this but this is
+    faster. This also has special handling of the optional MODSEQ part
+    of a SEARCH response.
+
+    The returned list is a SearchIds instance which has a *modseq*
+    attribute which contains the MODSEQ response (if returned by the
+    server).
+    """
+    if len(data) != 1:
+        raise ValueError("unexpected message list data")
+
+    message_data = data[0]
+    if not message_data:
+        return SearchIds()
+
+    if isinstance(message_data, bytes):
+        message_data = message_data.decode("ascii")
+
+    m = _msg_id_pattern.match(message_data)
+    if not m:
+        raise ValueError("unexpected message list format")
+
+    ids = SearchIds(int(n) for n in m.group(1).split())
+
+    # Parse any non-numeric part on the end using parse_response (this
+    # is likely to be the MODSEQ section).
+    extra = message_data[m.end(1) :]
+    if extra:
+        for item in parse_response([extra.encode("ascii")]):
+            if (
+                isinstance(item, tuple)
+                and len(item) == 2
+                and cast(bytes, item[0]).lower() == b"modseq"
+            ):
+                if TYPE_CHECKING:
+                    assert isinstance(item[1], int)
+                ids.modseq = item[1]
+            elif isinstance(item, int):
+                ids.append(item)
+    return ids
+
+
+def gen_parsed_response(text: List[bytes]) -> Iterator[_Atom]:
+    if not text:
+        return
+    src = TokenSource(text)
+
+    token = None
+    try:
+        for token in src:
+            yield atom(src, token)
+    except ProtocolError:
+        raise
+    except ValueError:
+        _, err, _ = sys.exc_info()
+        raise ProtocolError("%s: %r" % (str(err), token))
+
+
+_ParseFetchResponseInnerDict = Dict[
+    bytes, Optional[Union[datetime.datetime, int, BodyData, Envelope, _Atom]]
+]
+
+
+def parse_fetch_response(
+    text: List[bytes], normalise_times: bool = True, uid_is_key: bool = True
+) -> "defaultdict[int, _ParseFetchResponseInnerDict]":
+    """Pull apart IMAP FETCH responses as returned by imaplib.
+
+    Returns a dictionary, keyed by message ID. Each value a dictionary
+    keyed by FETCH field type (eg."RFC822").
+    """
+    if text == [None]:
+        return defaultdict()
+    response = gen_parsed_response(text)
+
+    parsed_response: "defaultdict[int, _ParseFetchResponseInnerDict]" = defaultdict(
+        dict
+    )
+    while True:
+        try:
+            msg_id = seq = _int_or_error(next(response), "invalid message ID")
+        except StopIteration:
+            break
+
+        try:
+            msg_response = next(response)
+        except StopIteration:
+            raise ProtocolError("unexpected EOF")
+
+        if not isinstance(msg_response, tuple):
+            raise ProtocolError("bad response type: %s" % repr(msg_response))
+        if len(msg_response) % 2:
+            raise ProtocolError(
+                "uneven number of response items: %s" % repr(msg_response)
+            )
+
+        # always return the sequence of the message, so it is available
+        # even if we return keyed by UID.
+        msg_data: _ParseFetchResponseInnerDict = {b"SEQ": seq}
+        for i in range(0, len(msg_response), 2):
+            msg_attribute = msg_response[i]
+            if TYPE_CHECKING:
+                assert isinstance(msg_attribute, bytes)
+            word = msg_attribute.upper()
+            value = msg_response[i + 1]
+
+            if word == b"UID":
+                uid = _int_or_error(value, "invalid UID")
+                if uid_is_key:
+                    msg_id = uid
+                else:
+                    msg_data[word] = uid
+            elif word == b"INTERNALDATE":
+                msg_data[word] = _convert_INTERNALDATE(value, normalise_times)
+            elif word == b"ENVELOPE":
+                msg_data[word] = _convert_ENVELOPE(value, normalise_times)
+            elif word in (b"BODY", b"BODYSTRUCTURE"):
+                if TYPE_CHECKING:
+                    assert isinstance(value, tuple)
+                msg_data[word] = BodyData.create(value)
+            else:
+                msg_data[word] = value
+
+        parsed_response[msg_id].update(msg_data)
+
+    return parsed_response
+
+
+def _int_or_error(value: _Atom, error_text: str) -> int:
+    try:
+        return int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        raise ProtocolError("%s: %s" % (error_text, repr(value)))
+
+
+def _convert_INTERNALDATE(
+    date_string: _Atom, normalise_times: bool = True
+) -> Optional[datetime.datetime]:
+    if date_string is None:
+        return None
+
+    try:
+        if TYPE_CHECKING:
+            assert isinstance(date_string, bytes)
+        return parse_to_datetime(date_string, normalise=normalise_times)
+    except ValueError:
+        return None
+
+
+def _convert_ENVELOPE(
+    envelope_response: _Atom, normalise_times: bool = True
+) -> Envelope:
+    if TYPE_CHECKING:
+        assert isinstance(envelope_response, tuple)
+    dt = None
+    if envelope_response[0]:
+        try:
+            if TYPE_CHECKING:
+                assert isinstance(envelope_response[0], bytes)
+            dt = parse_to_datetime(
+                envelope_response[0],
+                normalise=normalise_times,
+            )
+        except ValueError:
+            pass
+
+    subject = envelope_response[1]
+    in_reply_to = envelope_response[8]
+    message_id = envelope_response[9]
+    if TYPE_CHECKING:
+        assert isinstance(subject, bytes)
+        assert isinstance(in_reply_to, bytes)
+        assert isinstance(message_id, bytes)
+
+    # addresses contains a tuple of addresses
+    # from, sender, reply_to, to, cc, bcc headers
+    addresses: List[Optional[Tuple[Address, ...]]] = []
+    for addr_list in envelope_response[2:8]:
+        addrs = []
+        if addr_list:
+            if TYPE_CHECKING:
+                assert isinstance(addr_list, tuple)
+            for addr_tuple in addr_list:
+                if TYPE_CHECKING:
+                    assert isinstance(addr_tuple, tuple)
+                if addr_tuple:
+                    if TYPE_CHECKING:
+                        addr_tuple = cast(Tuple[bytes, bytes, bytes, bytes], addr_tuple)
+                    addrs.append(Address(*addr_tuple))
+            addresses.append(tuple(addrs))
+        else:
+            addresses.append(None)
+
+    return Envelope(
+        date=dt,
+        subject=subject,
+        from_=addresses[0],
+        sender=addresses[1],
+        reply_to=addresses[2],
+        to=addresses[3],
+        cc=addresses[4],
+        bcc=addresses[5],
+        in_reply_to=in_reply_to,
+        message_id=message_id,
+    )
+
+
+def atom(src: TokenSource, token: bytes) -> _Atom:
+    if token == b"(":
+        return parse_tuple(src)
+    if token == b"NIL":
+        return None
+    if token[:1] == b"{":
+        literal_len = int(token[1:-1])
+        literal_text = src.current_literal
+        if literal_text is None:
+            raise ProtocolError("No literal corresponds to %r" % token)
+        if len(literal_text) != literal_len:
+            raise ProtocolError(
+                "Expecting literal of size %d, got %d"
+                % (literal_len, len(literal_text))
+            )
+        return literal_text
+    if len(token) >= 2 and (token[:1] == token[-1:] == b'"'):
+        return token[1:-1]
+    if token.isdigit() and (token[:1] != b"0" or len(token) == 1):
+        # this prevents converting items like 0123 to 123
+        return int(token)
+    return token
+
+
+def parse_tuple(src: TokenSource) -> _Atom:
+    out: List[_Atom] = []
+    for token in src:
+        if token == b")":
+            return tuple(out)
+        out.append(atom(src, token))
+    # no terminator
+    raise ProtocolError('Tuple incomplete before "(%s"' % _fmt_tuple(out))
+
+
+def _fmt_tuple(t: List[_Atom]) -> str:
+    return " ".join(str(item) for item in t)

imapclient/response_types.py

@@ -0,0 +1,154 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+import dataclasses
+import datetime
+from email.utils import formataddr
+from typing import Any, List, Optional, Tuple, TYPE_CHECKING, Union
+
+from .typing_imapclient import _Atom
+from .util import to_unicode
+
+
+@dataclasses.dataclass
+class Envelope:
+    r"""Represents envelope structures of messages. Returned when parsing
+    ENVELOPE responses.
+
+    :ivar date: A datetime instance that represents the "Date" header.
+    :ivar subject: A string that contains the "Subject" header.
+    :ivar from\_: A tuple of Address objects that represent one or more
+      addresses from the "From" header, or None if header does not exist.
+    :ivar sender: As for from\_ but represents the "Sender" header.
+    :ivar reply_to: As for from\_ but represents the "Reply-To" header.
+    :ivar to: As for from\_ but represents the "To" header.
+    :ivar cc: As for from\_ but represents the "Cc" header.
+    :ivar bcc: As for from\_ but represents the "Bcc" recipients.
+    :ivar in_reply_to: A string that contains the "In-Reply-To" header.
+    :ivar message_id: A string that contains the "Message-Id" header.
+
+    A particular issue to watch out for is IMAP's handling of "group
+    syntax" in address fields. This is often encountered as a
+    recipient header of the form::
+
+        undisclosed-recipients:;
+
+    but can also be expressed per this more general example::
+
+        A group: a@example.com, B <b@example.org>;
+
+    This example would yield the following Address tuples::
+
+      Address(name=None, route=None, mailbox=u'A group', host=None)
+      Address(name=None, route=None, mailbox=u'a', host=u'example.com')
+      Address(name=u'B', route=None, mailbox=u'b', host=u'example.org')
+      Address(name=None, route=None, mailbox=None, host=None)
+
+    The first Address, where ``host`` is ``None``, indicates the start
+    of the group. The ``mailbox`` field contains the group name. The
+    final Address, where both ``mailbox`` and ``host`` are ``None``,
+    indicates the end of the group.
+
+    See :rfc:`3501#section-7.4.2` and :rfc:`2822` for further details.
+
+    """
+
+    date: Optional[datetime.datetime]
+    subject: bytes
+    from_: Optional[Tuple["Address", ...]]
+    sender: Optional[Tuple["Address", ...]]
+    reply_to: Optional[Tuple["Address", ...]]
+    to: Optional[Tuple["Address", ...]]
+    cc: Optional[Tuple["Address", ...]]
+    bcc: Optional[Tuple["Address", ...]]
+    in_reply_to: bytes
+    message_id: bytes
+
+
+@dataclasses.dataclass
+class Address:
+    """Represents electronic mail addresses. Used to store addresses in
+    :py:class:`Envelope`.
+
+    :ivar name: The address "personal name".
+    :ivar route: SMTP source route (rarely used).
+    :ivar mailbox: Mailbox name (what comes just before the @ sign).
+    :ivar host: The host/domain name.
+
+    As an example, an address header that looks like::
+
+        Mary Smith <mary@foo.com>
+
+    would be represented as::
+
+        Address(name=u'Mary Smith', route=None, mailbox=u'mary', host=u'foo.com')
+
+    See :rfc:`2822` for more detail.
+
+    See also :py:class:`Envelope` for information about handling of
+    "group syntax".
+    """
+
+    name: bytes
+    route: bytes
+    mailbox: bytes
+    host: bytes
+
+    def __str__(self) -> str:
+        if self.mailbox and self.host:
+            address = to_unicode(self.mailbox) + "@" + to_unicode(self.host)
+        else:
+            address = to_unicode(self.mailbox or self.host)
+
+        return formataddr((to_unicode(self.name), address))
+
+
+class SearchIds(List[int]):
+    """
+    Contains a list of message ids as returned by IMAPClient.search().
+
+    The *modseq* attribute will contain the MODSEQ value returned by
+    the server (only if the SEARCH command sent involved the MODSEQ
+    criteria). See :rfc:`4551` for more details.
+    """
+
+    def __init__(self, *args: Any):
+        super().__init__(*args)
+        self.modseq: Optional[int] = None
+
+
+_BodyDataType = Tuple[Union[bytes, int, "BodyData"], "_BodyDataType"]
+
+
+class BodyData(_BodyDataType):
+    """
+    Returned when parsing BODY and BODYSTRUCTURE responses.
+    """
+
+    @classmethod
+    def create(cls, response: Tuple[_Atom, ...]) -> "BodyData":
+        # In case of multipart messages we will see at least 2 tuples
+        # at the start. Nest these in to a list so that the returned
+        # response tuple always has a consistent number of elements
+        # regardless of whether the message is multipart or not.
+        if isinstance(response[0], tuple):
+            # Multipart, find where the message part tuples stop
+            parts = []
+            for i, part in enumerate(response):
+                if isinstance(part, bytes):
+                    break
+                if TYPE_CHECKING:
+                    assert isinstance(part, tuple)
+                parts.append(part)
+            # The runtime representation of BodyData mixes converted
+            # BodyData/list items with raw, not-yet-converted response
+            # atoms. _BodyDataType can't precisely express this shape, so
+            # the construction below can't be typed exactly.
+            body_parts = ([cls.create(part) for part in parts],) + response[i:]
+            return cls(body_parts)  # type: ignore[arg-type]
+        return cls(response)  # type: ignore[arg-type]
+
+    @property
+    def is_multipart(self) -> bool:
+        return isinstance(self[0], list)

imapclient/testable_imapclient.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+from typing import Any, Dict, List
+from unittest.mock import Mock
+
+from .imapclient import IMAPClient
+
+
+class TestableIMAPClient(IMAPClient):
+    """Wrapper of :py:class:`imapclient.IMAPClient` that mocks all
+    interaction with real IMAP server.
+
+    This class should only be used in tests, where you can safely
+    interact with imapclient without running commands on a real
+    IMAP account.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("somehost")
+
+    def _create_IMAP4(self) -> "MockIMAP4":
+        return MockIMAP4()
+
+
+class MockIMAP4(Mock):
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.use_uid = True
+        self.sent = b""  # Accumulates what was given to send()
+        self.tagged_commands: Dict[Any, Any] = {}
+        self.untagged_responses: Dict[Any, Any] = {}
+        self.capabilities: List[str] = []
+        self._starttls_done = False
+
+    def send(self, data: bytes) -> None:
+        self.sent += data
+
+    def _new_tag(self) -> str:
+        return "tag"

imapclient/tls.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2023, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+"""
+This module contains IMAPClient's functionality related to Transport
+Layer Security (TLS a.k.a. SSL).
+"""
+
+import imaplib
+import socket
+import ssl
+from typing import Optional
+
+
+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)
+
+    return ssl_context.wrap_socket(sock, server_hostname=host)
+
+
+class IMAP4_TLS(imaplib.IMAP4):
+    """IMAP4 client class for TLS/SSL connections.
+
+    Adapted from imaplib.IMAP4_SSL.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int = 993,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        timeout: Optional[float] = None,
+    ):
+        self.ssl_context = ssl_context
+        self._timeout = timeout
+        super().__init__(host, port)
+
+    def _create_socket(self, timeout: Optional[float]) -> socket.socket:
+        sock = socket.create_connection((self.host, self.port), timeout=timeout)
+
+        return wrap_socket(sock, self.ssl_context, self.host)

imapclient/typing_imapclient.py

@@ -0,0 +1,4 @@
+from typing import Tuple, Union
+
+_AtomPart = Union[None, int, bytes]
+_Atom = Union[_AtomPart, Tuple["_Atom", ...]]