@backtomyfuture/exchange-cli-darwin-arm64 0.1.9 → 0.1.11

package/bin/_internal/exchangelib/attachments.py

@@ -0,0 +1,268 @@
+import io
+import logging
+import mimetypes
+
+from .errors import InvalidTypeError
+from .fields import (
+    Base64Field,
+    BooleanField,
+    DateTimeField,
+    EWSElementField,
+    FieldPath,
+    IdField,
+    IntegerField,
+    ItemField,
+    TextField,
+    URIField,
+)
+from .properties import BaseItemId, EWSElement, EWSMeta
+
+log = logging.getLogger(__name__)
+
+
+class AttachmentId(BaseItemId):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/attachmentid"""
+
+    ELEMENT_NAME = "AttachmentId"
+
+    ID_ATTR = "Id"
+    ROOT_ID_ATTR = "RootItemId"
+    ROOT_CHANGEKEY_ATTR = "RootItemChangeKey"
+
+    id = IdField(field_uri=ID_ATTR, is_required=True)
+    root_id = IdField(field_uri=ROOT_ID_ATTR)
+    root_changekey = IdField(field_uri=ROOT_CHANGEKEY_ATTR)
+
+
+class Attachment(EWSElement, metaclass=EWSMeta):
+    """Base class for FileAttachment and ItemAttachment."""
+
+    attachment_id = EWSElementField(value_cls=AttachmentId)
+    name = TextField(field_uri="Name")
+    content_type = TextField(field_uri="ContentType")
+    content_id = TextField(field_uri="ContentId")
+    content_location = URIField(field_uri="ContentLocation")
+    size = IntegerField(field_uri="Size", is_read_only=True)  # Attachment size in bytes
+    last_modified_time = DateTimeField(field_uri="LastModifiedTime")
+    is_inline = BooleanField(field_uri="IsInline")
+
+    __slots__ = ("parent_item",)
+
+    def __init__(self, **kwargs):
+        self.parent_item = kwargs.pop("parent_item", None)
+        super().__init__(**kwargs)
+
+    def clean(self, version=None):
+        from .items import Item
+
+        if self.parent_item is not None and not isinstance(self.parent_item, Item):
+            raise InvalidTypeError("parent_item", self.parent_item, Item)
+        if self.content_type is None and self.name is not None:
+            self.content_type = mimetypes.guess_type(self.name)[0] or "application/octet-stream"
+        super().clean(version=version)
+
+    def attach(self):
+        from .services import CreateAttachment
+
+        # Adds this attachment to an item and updates the changekey of the parent item
+        if self.attachment_id:
+            raise ValueError("This attachment has already been created")
+        if not self.parent_item or not self.parent_item.account:
+            raise ValueError(f"Parent item {self.parent_item} must have an account")
+        item = CreateAttachment(account=self.parent_item.account).get(parent_item=self.parent_item, items=[self])
+        attachment_id = item.attachment_id
+        self.parent_item.changekey = attachment_id.root_changekey
+        # EWS does not like receiving root_id and root_changekey on subsequent requests
+        attachment_id.root_id = None
+        attachment_id.root_changekey = None
+        self.attachment_id = attachment_id
+
+    def detach(self):
+        from .services import DeleteAttachment
+
+        # Deletes an attachment remotely and updates the changekey of the parent item
+        if not self.attachment_id:
+            raise ValueError("This attachment has not been created")
+        if not self.parent_item or not self.parent_item.account:
+            raise ValueError(f"Parent item {self.parent_item} must have an account")
+        DeleteAttachment(account=self.parent_item.account).get(items=[self.attachment_id])
+        self.parent_item = None
+        self.attachment_id = None
+
+    def __hash__(self):
+        if self.attachment_id:
+            return hash(self.attachment_id)
+        # Be careful to avoid recursion on the back-reference to the parent item
+        return hash(tuple(getattr(self, f) for f in self._slots_keys if f != "parent_item"))
+
+    def __repr__(self):
+        args_str = ", ".join(
+            f"{f.name}={getattr(self, f.name)!r}" for f in self.FIELDS if f.name not in ("_item", "_content")
+        )
+        return f"{self.__class__.__name__}({args_str})"
+
+
+class FileAttachment(Attachment):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/fileattachment"""
+
+    ELEMENT_NAME = "FileAttachment"
+
+    is_contact_photo = BooleanField(field_uri="IsContactPhoto")
+    _content = Base64Field(field_uri="Content")
+
+    __slots__ = ("_fp",)
+
+    def __init__(self, **kwargs):
+        kwargs["_content"] = kwargs.pop("content", None)
+        super().__init__(**kwargs)
+        self._fp = None
+
+    @property
+    def fp(self):
+        # Return a file-like object for the content. This avoids creating multiple in-memory copies of the content.
+        if self._fp is None:
+            self._init_fp()
+        return self._fp
+
+    def _init_fp(self):
+        # Create a file-like object for the attachment content. We try hard to reduce memory consumption, so we never
+        # store the full attachment content in-memory.
+        if not self.parent_item or not self.parent_item.account:
+            raise ValueError(f"{self.__class__.__name__} must have an account")
+        self._fp = FileAttachmentIO(attachment=self)
+
+    @property
+    def content(self):
+        """Return the attachment content. Stores a local copy of the content in case you want to upload the attachment
+        again later.
+        """
+        if self.attachment_id is None:
+            return self._content
+        if self._content is not None:
+            return self._content
+        # We have an ID to the data but still haven't called GetAttachment to get the actual data. Do that now.
+        with self.fp as fp:
+            self._content = fp.read()
+        return self._content
+
+    @content.setter
+    def content(self, value):
+        """Replace the attachment content."""
+        if not isinstance(value, bytes):
+            raise InvalidTypeError("value", value, bytes)
+        self._content = value
+
+    @classmethod
+    def from_xml(cls, elem, account):
+        kwargs = {f.name: f.from_xml(elem=elem, account=account) for f in cls.FIELDS}
+        kwargs["content"] = kwargs.pop("_content")
+        cls._clear(elem)
+        return cls(**kwargs)
+
+    def to_xml(self, version):
+        self._content = self.content  # Make sure content is available, to avoid ErrorRequiredPropertyMissing
+        return super().to_xml(version=version)
+
+    def __getstate__(self):
+        # The fp does not need to be pickled
+        state = {k: getattr(self, k) for k in self._slots_keys}
+        del state["_fp"]
+        return state
+
+    def __setstate__(self, state):
+        # Restore the fp
+        for k in self._slots_keys:
+            setattr(self, k, state.get(k))
+        self._fp = None
+
+
+class ItemAttachment(Attachment):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/itemattachment"""
+
+    ELEMENT_NAME = "ItemAttachment"
+
+    _item = ItemField(field_uri="Item")
+
+    def __init__(self, **kwargs):
+        kwargs["_item"] = kwargs.pop("item", None)
+        super().__init__(**kwargs)
+
+    @property
+    def item(self):
+        from .folders import BaseFolder
+        from .services import GetAttachment
+
+        if self.attachment_id is None:
+            return self._item
+        if self._item is not None:
+            return self._item
+        # We have an ID to the data but still haven't called GetAttachment to get the actual data. Do that now.
+        if not self.parent_item or not self.parent_item.account:
+            raise ValueError(f"{self.__class__.__name__} must have an account")
+        additional_fields = {
+            FieldPath(field=f) for f in BaseFolder.allowed_item_fields(version=self.parent_item.account.version)
+        }
+        attachment = GetAttachment(account=self.parent_item.account).get(
+            items=[self.attachment_id],
+            include_mime_content=True,
+            body_type=None,
+            filter_html_content=None,
+            additional_fields=additional_fields,
+        )
+        self._item = attachment.item
+        return self._item
+
+    @item.setter
+    def item(self, value):
+        from .items import Item
+
+        if not isinstance(value, Item):
+            raise InvalidTypeError("value", value, Item)
+        self._item = value
+
+    @classmethod
+    def from_xml(cls, elem, account):
+        kwargs = {f.name: f.from_xml(elem=elem, account=account) for f in cls.FIELDS}
+        kwargs["item"] = kwargs.pop("_item")
+        cls._clear(elem)
+        return cls(**kwargs)
+
+
+class FileAttachmentIO(io.RawIOBase):
+    """A BytesIO where the stream of data comes from the GetAttachment service."""
+
+    def __init__(self, attachment):
+        self._attachment = attachment
+        self._stream = None
+        self._overflow = None
+
+    def readable(self):
+        return True
+
+    @property
+    def closed(self):
+        return self._stream is None
+
+    def readinto(self, b):
+        buf_size = len(b)  # We can't return more than l bytes
+        try:
+            chunk = self._overflow or next(self._stream)
+        except StopIteration:
+            return 0
+        else:
+            output, self._overflow = chunk[:buf_size], chunk[buf_size:]
+            b[: len(output)] = output
+            return len(output)
+
+    def __enter__(self):
+        from .services import GetAttachment
+
+        self._stream = GetAttachment(account=self._attachment.parent_item.account).stream_file_content(
+            attachment_id=self._attachment.attachment_id
+        )
+        self._overflow = None
+        return io.BufferedReader(self, buffer_size=io.DEFAULT_BUFFER_SIZE)
+
+    def __exit__(self, *args, **kwargs):
+        self._stream = None
+        self._overflow = None

package/bin/_internal/exchangelib/autodiscover/__init__.py

@@ -0,0 +1,24 @@
+from .cache import AutodiscoverCache, autodiscover_cache
+from .discovery import Autodiscovery, discover
+from .protocol import AutodiscoverProtocol
+
+
+def close_connections():
+    with autodiscover_cache:
+        autodiscover_cache.close()
+
+
+def clear_cache():
+    with autodiscover_cache:
+        autodiscover_cache.clear()
+
+
+__all__ = [
+    "AutodiscoverCache",
+    "AutodiscoverProtocol",
+    "Autodiscovery",
+    "autodiscover_cache",
+    "clear_cache",
+    "close_connections",
+    "discover",
+]

package/bin/_internal/exchangelib/autodiscover/cache.py

@@ -0,0 +1,150 @@
+import getpass
+import logging
+import shelve
+import sys
+import tempfile
+from contextlib import contextmanager, suppress
+from pathlib import Path
+from threading import RLock
+
+from ..configuration import Configuration
+from .protocol import AutodiscoverProtocol
+
+log = logging.getLogger(__name__)
+
+
+def shelve_filename():
+    # Add the version of the cache format to the filename. If we change the format of the cached data, this version
+    # must be bumped. Otherwise, new versions of this package cannot open cache files generated by older versions.
+    version = 2
+    # 'shelve' may pickle objects using different pickle protocol versions. Append the python major+minor version
+    # numbers to the filename. Also append the username, to avoid permission errors.
+    major, minor = sys.version_info[:2]
+    try:
+        user = getpass.getuser()
+    except KeyError:
+        # getuser() fails on some systems. Provide a sane default. See issue #448
+        user = "exchangelib"
+    return f"exchangelib.{version}.cache.{user}.py{major}{minor}"
+
+
+AUTODISCOVER_PERSISTENT_STORAGE = Path(tempfile.gettempdir(), shelve_filename())
+
+
+@contextmanager
+def shelve_open_with_failover(file):
+    # We can expect empty or corrupt files. Whatever happens, just delete the cache file and try again.
+    # 'shelve' may add a backend-specific suffix to the file, so also delete all files with a suffix.
+    # We don't know which file caused the error, so just delete them all.
+    try:
+        shelve_handle = shelve.open(str(file))
+        # Try to actually use the file. Some implementations may allow opening the file but then throw
+        # errors on access.
+        with suppress(KeyError):
+            _ = shelve_handle[""]
+    except Exception as e:
+        for f in file.parent.glob(f"{file.name}*"):
+            log.warning("Deleting invalid cache file %s (%r)", f, e)
+            f.unlink()
+        shelve_handle = shelve.open(str(file))
+    yield shelve_handle
+
+
+class AutodiscoverCache:
+    """Stores the translation from (email domain, credentials) -> AutodiscoverProtocol object, so we can re-use TCP
+    connections to an autodiscover server within the same process. Also persists the email domain -> (autodiscover
+    endpoint URL, auth_type) translation to the filesystem so the cache can be shared between multiple processes.
+
+    According to Microsoft, we may forever cache the (email domain -> autodiscover endpoint URL) mapping, or until
+    it stops responding. My previous experience with Exchange products in mind, I'm not sure if I should trust that
+    advice. But it could save some valuable seconds every time we start a new connection to a known server. In any
+    case, the persistent storage must not contain any sensitive information since the cache could be readable by
+    unprivileged users. Domain, endpoint and auth_type are OK to cache since this info is make publicly available on
+    HTTP and DNS servers via the autodiscover protocol. Just don't persist any credential info.
+
+    If an autodiscover lookup fails for any reason, the corresponding cache entry must be purged.
+
+    'shelve' is supposedly thread-safe and process-safe, which suits our needs.
+    """
+
+    def __init__(self):
+        self._protocols = {}  # Mapping from (domain, credentials) to AutodiscoverProtocol
+        self._lock = RLock()
+
+    @property
+    def _storage_file(self):
+        return AUTODISCOVER_PERSISTENT_STORAGE
+
+    def clear(self):
+        # Wipe the entire cache
+        with shelve_open_with_failover(self._storage_file) as db:
+            db.clear()
+        self._protocols.clear()
+
+    def __len__(self):
+        return len(self._protocols)
+
+    def __contains__(self, key):
+        domain = key[0]
+        with shelve_open_with_failover(self._storage_file) as db:
+            return str(domain) in db
+
+    def __getitem__(self, key):
+        protocol = self._protocols.get(key)
+        if protocol:
+            return protocol
+        domain, credentials = key
+        with shelve_open_with_failover(self._storage_file) as db:
+            endpoint, auth_type, retry_policy = db[str(domain)]  # It's OK to fail with KeyError here
+        protocol = AutodiscoverProtocol(
+            config=Configuration(
+                service_endpoint=endpoint, credentials=credentials, auth_type=auth_type, retry_policy=retry_policy
+            )
+        )
+        self._protocols[key] = protocol
+        return protocol
+
+    def __setitem__(self, key, protocol):
+        # Populate both local and persistent cache
+        domain = key[0]
+        with shelve_open_with_failover(self._storage_file) as db:
+            # Don't change this payload without bumping the cache file version in shelve_filename()
+            db[str(domain)] = (protocol.service_endpoint, protocol.auth_type, protocol.retry_policy)
+        self._protocols[key] = protocol
+
+    def __delitem__(self, key):
+        # Empty both local and persistent cache. Don't fail on non-existing entries because we could end here
+        # multiple times due to race conditions.
+        domain = key[0]
+        with shelve_open_with_failover(self._storage_file) as db, suppress(KeyError):
+            del db[str(domain)]
+        with suppress(KeyError):
+            del self._protocols[key]
+
+    def close(self):
+        # Close all open connections
+        for (domain, _), protocol in self._protocols.items():
+            log.debug("Domain %s: Closing sessions", domain)
+            protocol.close()
+            del protocol
+        self._protocols.clear()
+
+    def __enter__(self):
+        self._lock.__enter__()
+
+    def __exit__(self, *args, **kwargs):
+        self._lock.__exit__(*args, **kwargs)
+
+    def __del__(self):
+        # pylint: disable=bare-except
+        try:
+            self.close()
+        except Exception:  # nosec
+            # __del__ should never fail
+            pass
+
+    def __str__(self):
+        return str(self._protocols)
+
+
+autodiscover_cache = AutodiscoverCache()