IMAPClient 4.0.0__py3-none-any.whl

imapclient/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+# version_info provides the version number in programmer friendly way.
+# The 4th part will be either alpha, beta or final.
+
+from .imapclient import *  # noqa: F401,F403
+from .response_parser import *  # noqa: F401,F403
+from .tls import *  # noqa: F401,F403
+from .version import version as __version__  # noqa: F401
+from .version import version_info  # noqa: F401

imapclient/config.py

@@ -0,0 +1,219 @@
+# Copyright (c) 2015, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+import argparse
+import configparser
+import json
+import os
+import ssl
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional, Tuple, TYPE_CHECKING, TypeVar
+
+import imapclient
+
+
+def getenv(name: str, default: Optional[str]) -> Optional[str]:
+    return os.environ.get("imapclient_" + name, default)
+
+
+def get_config_defaults() -> Dict[str, Any]:
+    return {
+        "username": getenv("username", None),
+        "password": getenv("password", None),
+        "ssl": True,
+        "ssl_check_hostname": True,
+        "ssl_verify_cert": True,
+        "ssl_ca_file": None,
+        "timeout": None,
+        "starttls": False,
+        "stream": False,
+        "oauth2": False,
+        "oauth2_client_id": getenv("oauth2_client_id", None),
+        "oauth2_client_secret": getenv("oauth2_client_secret", None),
+        "oauth2_refresh_token": getenv("oauth2_refresh_token", None),
+        "expect_failure": None,
+    }
+
+
+def parse_config_file(filename: str) -> argparse.Namespace:
+    """Parse INI files containing IMAP connection details.
+
+    Used by imapclient.livetest and imapclient.interact
+    """
+
+    parser = configparser.ConfigParser(get_string_config_defaults())
+    parser.read(filename)
+
+    conf = _read_config_section(parser, "DEFAULT")
+    if conf.expect_failure:
+        raise ValueError("expect_failure should not be set for the DEFAULT section")
+
+    conf.alternates = {}
+    for section in parser.sections():
+        # pylint: disable=no-member
+        conf.alternates[section] = _read_config_section(parser, section)
+
+    return conf
+
+
+def get_string_config_defaults() -> Dict[str, str]:
+    out = {}
+    for k, v in get_config_defaults().items():
+        if v is True:
+            v = "true"
+        elif v is False:
+            v = "false"
+        elif not v:
+            v = ""
+        out[k] = v
+    return out
+
+
+T = TypeVar("T")
+
+
+def _read_config_section(
+    parser: configparser.ConfigParser, section: str
+) -> argparse.Namespace:
+    def get(name: str) -> str:
+        return parser.get(section, name)
+
+    def getboolean(name: str) -> bool:
+        return parser.getboolean(section, name)
+
+    def get_allowing_none(name: str, typefunc: Callable[[str], T]) -> Optional[T]:
+        try:
+            v = parser.get(section, name)
+        except configparser.NoOptionError:
+            return None
+        if not v:
+            return None
+        return typefunc(v)
+
+    def getint(name: str) -> Optional[int]:
+        return get_allowing_none(name, int)
+
+    def getfloat(name: str) -> Optional[float]:
+        return get_allowing_none(name, float)
+
+    ssl_ca_file = get("ssl_ca_file")
+    if ssl_ca_file:
+        ssl_ca_file = os.path.expanduser(ssl_ca_file)
+
+    return argparse.Namespace(
+        host=get("host"),
+        port=getint("port"),
+        ssl=getboolean("ssl"),
+        starttls=getboolean("starttls"),
+        ssl_check_hostname=getboolean("ssl_check_hostname"),
+        ssl_verify_cert=getboolean("ssl_verify_cert"),
+        ssl_ca_file=ssl_ca_file,
+        timeout=getfloat("timeout"),
+        stream=getboolean("stream"),
+        username=get("username"),
+        password=get("password"),
+        oauth2=getboolean("oauth2"),
+        oauth2_client_id=get("oauth2_client_id"),
+        oauth2_client_secret=get("oauth2_client_secret"),
+        oauth2_refresh_token=get("oauth2_refresh_token"),
+        expect_failure=get("expect_failure"),
+    )
+
+
+OAUTH2_REFRESH_URLS = {
+    "imap.gmail.com": "https://accounts.google.com/o/oauth2/token",
+    "imap.mail.yahoo.com": "https://api.login.yahoo.com/oauth2/get_token",
+}
+
+
+def refresh_oauth2_token(
+    hostname: str, client_id: str, client_secret: str, refresh_token: str
+) -> str:
+    url = OAUTH2_REFRESH_URLS.get(hostname)
+    if not url:
+        raise ValueError("don't know where to refresh OAUTH2 token for %r" % hostname)
+
+    post = {
+        "client_id": client_id.encode("ascii"),
+        "client_secret": client_secret.encode("ascii"),
+        "refresh_token": refresh_token.encode("ascii"),
+        "grant_type": b"refresh_token",
+    }
+    with urllib.request.urlopen(
+        url, urllib.parse.urlencode(post).encode("ascii")
+    ) as request:
+        response = request.read()
+    result = json.loads(response.decode("ascii"))["access_token"]
+    if TYPE_CHECKING:
+        assert isinstance(result, str)
+    return result
+
+
+# Tokens are expensive to refresh so use the same one for the duration of the process.
+_oauth2_cache: Dict[Tuple[str, str, str, str], str] = {}
+
+
+def get_oauth2_token(
+    hostname: str, client_id: str, client_secret: str, refresh_token: str
+) -> str:
+    cache_key = (hostname, client_id, client_secret, refresh_token)
+    token = _oauth2_cache.get(cache_key)
+    if token:
+        return token
+
+    token = refresh_oauth2_token(hostname, client_id, client_secret, refresh_token)
+    _oauth2_cache[cache_key] = token
+    return token
+
+
+def create_client_from_config(
+    conf: argparse.Namespace, login: bool = True
+) -> imapclient.IMAPClient:
+    assert conf.host, "missing host"
+
+    ssl_context = None
+    if conf.ssl:
+        ssl_context = ssl.create_default_context()
+        ssl_context.check_hostname = conf.ssl_check_hostname
+        if not conf.ssl_verify_cert:
+            ssl_context.verify_mode = ssl.CERT_NONE
+        if conf.ssl_ca_file:
+            ssl_context.load_verify_locations(cafile=conf.ssl_ca_file)
+
+    client = imapclient.IMAPClient(
+        conf.host,
+        port=conf.port,
+        ssl=conf.ssl,
+        ssl_context=ssl_context,
+        stream=conf.stream,
+        timeout=conf.timeout,
+    )
+    if not login:
+        return client
+
+    try:
+        if conf.starttls:
+            client.starttls()
+
+        if conf.oauth2:
+            assert conf.oauth2_client_id, "missing oauth2 id"
+            assert conf.oauth2_client_secret, "missing oauth2 secret"
+            assert conf.oauth2_refresh_token, "missing oauth2 refresh token"
+            access_token = get_oauth2_token(
+                conf.host,
+                conf.oauth2_client_id,
+                conf.oauth2_client_secret,
+                conf.oauth2_refresh_token,
+            )
+            client.oauth2_login(conf.username, access_token)
+
+        elif not conf.stream:
+            assert conf.username, "missing username"
+            assert conf.password, "missing password"
+            client.login(conf.username, conf.password)
+        return client
+    except:  # noqa: E722
+        client.shutdown()
+        raise

imapclient/datetime_util.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+import re
+from datetime import datetime
+from email.utils import parsedate_tz
+
+from .fixed_offset import FixedOffset
+
+_SHORT_MONTHS = " Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(" ")
+
+
+def parse_to_datetime(timestamp: bytes, normalise: bool = True) -> datetime:
+    """Convert an IMAP datetime string to a datetime.
+
+    If normalise is True (the default), then the returned datetime
+    will be timezone-naive but adjusted to the local time.
+
+    If normalise is False, then the returned datetime will be
+    unadjusted but will contain timezone information as per the input.
+    """
+    time_tuple = parsedate_tz(_munge(timestamp))
+    if time_tuple is None:
+        raise ValueError("couldn't parse datetime %r" % timestamp)
+
+    tz_offset_seconds = time_tuple[-1]
+    tz = None
+    if tz_offset_seconds is not None:
+        tz = FixedOffset(tz_offset_seconds / 60)
+
+    dt = datetime(*time_tuple[:6], tzinfo=tz)
+    if normalise and tz:
+        dt = datetime_to_native(dt)
+
+    return dt
+
+
+def datetime_to_native(dt: datetime) -> datetime:
+    return dt.astimezone(FixedOffset.for_system()).replace(tzinfo=None)
+
+
+def datetime_to_INTERNALDATE(dt: datetime) -> str:
+    """Convert a datetime instance to a IMAP INTERNALDATE string.
+
+    If timezone information is missing the current system
+    timezone is used.
+    """
+    if not dt.tzinfo:
+        dt = dt.replace(tzinfo=FixedOffset.for_system())
+    fmt = "%d-" + _SHORT_MONTHS[dt.month] + "-%Y %H:%M:%S %z"
+    return dt.strftime(fmt)
+
+
+# Matches timestamp strings where the time separator is a dot (see
+# issue #154). For example: 'Sat, 8 May 2010 16.03.09 +0200'
+_rfc822_dotted_time = re.compile(r"\w+, ?\d{1,2} \w+ \d\d(\d\d)? \d\d?\.\d\d?\.\d\d?.*")
+
+
+def _munge(timestamp: bytes) -> str:
+    s = timestamp.decode("latin-1")  # parsedate_tz only works with strings
+    if _rfc822_dotted_time.match(s):
+        return s.replace(".", ":")
+    return s
+
+
+def format_criteria_date(dt: datetime) -> bytes:
+    """Format a date or datetime instance for use in IMAP search criteria."""
+    out = "%02d-%s-%d" % (dt.day, _SHORT_MONTHS[dt.month], dt.year)
+    return out.encode("ascii")

imapclient/exceptions.py

@@ -0,0 +1,43 @@
+import imaplib
+
+# Base class allowing to catch any IMAPClient related exceptions
+# To ensure backward compatibility, we "rename" the imaplib general
+# exception class, so we can catch its exceptions without having to
+# deal with it in IMAPClient codebase
+
+IMAPClientError = imaplib.IMAP4.error
+IMAPClientAbortError = imaplib.IMAP4.abort
+IMAPClientReadOnlyError = imaplib.IMAP4.readonly
+
+
+class CapabilityError(IMAPClientError):
+    """
+    The command tried by the user needs a capability not installed
+    on the IMAP server
+    """
+
+
+class LoginError(IMAPClientError):
+    """
+    A connection has been established with the server but an error
+    occurred during the authentication.
+    """
+
+
+class IllegalStateError(IMAPClientError):
+    """
+    The command tried needs a different state to be executed. This
+    means the user is not logged in or the command needs a folder to
+    be selected.
+    """
+
+
+class InvalidCriteriaError(IMAPClientError):
+    """
+    A command using a search criteria failed, probably due to a syntax
+    error in the criteria string.
+    """
+
+
+class ProtocolError(IMAPClientError):
+    """The server replied with a response that violates the IMAP protocol."""

imapclient/fixed_offset.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2014, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+import datetime
+import time
+from typing import Optional
+
+ZERO = datetime.timedelta(0)
+
+
+class FixedOffset(datetime.tzinfo):
+    """
+    This class describes fixed timezone offsets in hours and minutes
+    east from UTC
+    """
+
+    def __init__(self, minutes: float) -> None:
+        self.__offset = datetime.timedelta(minutes=minutes)
+
+        sign = "+"
+        if minutes < 0:
+            sign = "-"
+        hours, remaining_mins = divmod(abs(minutes), 60)
+        self.__name = "%s%02d%02d" % (sign, hours, remaining_mins)
+
+    def utcoffset(self, _: Optional[datetime.datetime]) -> datetime.timedelta:
+        return self.__offset
+
+    def tzname(self, _: Optional[datetime.datetime]) -> str:
+        return self.__name
+
+    def dst(self, _: Optional[datetime.datetime]) -> datetime.timedelta:
+        return ZERO
+
+    @classmethod
+    def for_system(cls) -> "FixedOffset":
+        """Return a FixedOffset instance for the current working timezone and
+        DST conditions.
+        """
+        if time.localtime().tm_isdst and time.daylight:
+            offset = time.altzone
+        else:
+            offset = time.timezone
+        return cls(-offset // 60)

imapclient/imap4.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2015, Menno Smits
+# Released subject to the New BSD License
+# Please see http://en.wikipedia.org/wiki/BSD_licenses
+
+import imaplib
+import socket
+from typing import Optional
+
+
+class IMAP4WithTimeout(imaplib.IMAP4):
+    def __init__(self, address: str, port: int, timeout: Optional[float]) -> None:
+        self._timeout = timeout
+        super().__init__(address, port, timeout=timeout)
+
+    def _create_socket(self, timeout: Optional[float] = None) -> socket.socket:
+        return socket.create_connection(
+            (self.host, self.port), timeout if timeout is not None else self._timeout
+        )

imapclient/imap_utf7.py

@@ -0,0 +1,108 @@
+# This file contains two main methods used to encode and decode UTF-7
+# string, described in the RFC 3501. There are some variations specific
+# to IMAP4rev1, so the built-in Python UTF-7 codec can't be used instead.
+#
+# The main difference is the shift character (used to switch from ASCII to
+# base64 encoding context), which is & in this modified UTF-7 convention,
+# since + is considered as mainly used in mailbox names.
+# Other variations and examples can be found in the RFC 3501, section 5.1.3.
+
+import binascii
+from typing import List, Union
+
+
+def encode(s: Union[str, bytes]) -> bytes:
+    """Encode a folder name using IMAP modified UTF-7 encoding.
+
+    Input is unicode; output is bytes (Python 3) or str (Python 2). If
+    non-unicode input is provided, the input is returned unchanged.
+    """
+    if not isinstance(s, str):
+        return s
+
+    res = bytearray()
+
+    b64_buffer: List[str] = []
+
+    def consume_b64_buffer(buf: List[str]) -> None:
+        """
+        Consume the buffer by encoding it into a modified base 64 representation
+        and surround it with shift characters & and -
+        """
+        if buf:
+            res.extend(b"&" + base64_utf7_encode(buf) + b"-")
+            del buf[:]
+
+    for c in s:
+        # printable ascii case should not be modified
+        o = ord(c)
+        if 0x20 <= o <= 0x7E:
+            consume_b64_buffer(b64_buffer)
+            # Special case: & is used as shift character so we need to escape it in ASCII
+            if o == 0x26:  # & = 0x26
+                res.extend(b"&-")
+            else:
+                res.append(o)
+
+        # Bufferize characters that will be encoded in base64 and append them later
+        # in the result, when iterating over ASCII character or the end of string
+        else:
+            b64_buffer.append(c)
+
+    # Consume the remaining buffer if the string finish with non-ASCII characters
+    consume_b64_buffer(b64_buffer)
+
+    return bytes(res)
+
+
+AMPERSAND_ORD = ord("&")
+DASH_ORD = ord("-")
+
+
+def decode(s: Union[bytes, str]) -> str:
+    """Decode a folder name from IMAP modified UTF-7 encoding to unicode.
+
+    Input is bytes (Python 3) or str (Python 2); output is always
+    unicode. If non-bytes/str input is provided, the input is returned
+    unchanged.
+    """
+    if not isinstance(s, bytes):
+        return s
+
+    res = []
+    # Store base64 substring that will be decoded once stepping on end shift character
+    b64_buffer = bytearray()
+    for c in s:
+        # Shift character without anything in buffer -> starts storing base64 substring
+        if c == AMPERSAND_ORD and not b64_buffer:
+            b64_buffer.append(c)
+        # End shift char. -> append the decoded buffer to the result and reset it
+        elif c == DASH_ORD and b64_buffer:
+            # Special case &-, representing "&" escaped
+            if len(b64_buffer) == 1:
+                res.append("&")
+            else:
+                res.append(base64_utf7_decode(b64_buffer[1:]))
+            b64_buffer = bytearray()
+        # Still buffering between the shift character and the shift back to ASCII
+        elif b64_buffer:
+            b64_buffer.append(c)
+        # No buffer initialized yet, should be an ASCII printable char
+        else:
+            res.append(chr(c))
+
+    # Decode the remaining buffer if any
+    if b64_buffer:
+        res.append(base64_utf7_decode(b64_buffer[1:]))
+
+    return "".join(res)
+
+
+def base64_utf7_encode(buffer: List[str]) -> bytes:
+    s = "".join(buffer).encode("utf-16be")
+    return binascii.b2a_base64(s).rstrip(b"\n=").replace(b"/", b",")
+
+
+def base64_utf7_decode(s: bytearray) -> str:
+    s_utf7 = b"+" + s.replace(b",", b"/") + b"-"
+    return s_utf7.decode("utf-7")