@backtomyfuture/exchange-cli-darwin-x64 0.1.10

package/bin/_internal/exchangelib/folders/queryset.py

@@ -0,0 +1,187 @@
+import logging
+from copy import deepcopy
+
+from ..errors import ErrorFolderNotFound, ErrorItemNotFound, ErrorNoPublicFolderReplicaAvailable, InvalidTypeError
+from ..properties import FolderId, InvalidField
+from ..queryset import DoesNotExist, MultipleObjectsReturned
+from ..restriction import Q
+
+# Traversal enums
+SHALLOW = "Shallow"
+SOFT_DELETED = "SoftDeleted"
+DEEP = "Deep"
+FOLDER_TRAVERSAL_CHOICES = (SHALLOW, DEEP, SOFT_DELETED)
+
+MISSING_FOLDER_ERRORS = (ErrorFolderNotFound, ErrorItemNotFound, ErrorNoPublicFolderReplicaAvailable)
+
+
+log = logging.getLogger(__name__)
+
+
+class FolderQuerySet:
+    """A QuerySet-like class for finding sub-folders of a folder collection."""
+
+    def __init__(self, folder_collection):
+        from .collections import FolderCollection
+
+        if not isinstance(folder_collection, FolderCollection):
+            raise InvalidTypeError("folder_collection", folder_collection, FolderCollection)
+        self.folder_collection = folder_collection
+        self.q = Q()  # Default to no restrictions
+        self.only_fields = None
+        self._depth = None
+
+    def _copy_cls(self):
+        return self.__class__(folder_collection=self.folder_collection)
+
+    def _copy_self(self):
+        """Chaining operations must make a copy of self before making any modifications."""
+        new_qs = self._copy_cls()
+        new_qs.q = deepcopy(self.q)
+        new_qs.only_fields = self.only_fields
+        new_qs._depth = self._depth
+        return new_qs
+
+    def only(self, *args):
+        """Restrict the fields returned. 'name' and 'folder_class' are always returned."""
+        from .base import Folder
+
+        # Sub-folders will always be of class Folder
+        all_fields = self.folder_collection.get_folder_fields(target_cls=Folder, is_complex=None)
+        all_fields.update(Folder.attribute_fields())
+        only_fields = []
+        for arg in args:
+            for field_path in all_fields:
+                if field_path.field.name == arg:
+                    only_fields.append(field_path)
+                    break
+            else:
+                raise InvalidField(f"Unknown field {arg!r} on folders {self.folder_collection.folders}")
+        new_qs = self._copy_self()
+        new_qs.only_fields = only_fields
+        return new_qs
+
+    def depth(self, depth):
+        """Specify the search depth. Possible values are: SHALLOW or DEEP.
+
+        :param depth:
+        """
+        new_qs = self._copy_self()
+        new_qs._depth = depth
+        return new_qs
+
+    def get(self, *args, **kwargs):
+        """Return the query result as exactly one item. Raises DoesNotExist if there are no results, and
+        MultipleObjectsReturned if there are multiple results.
+        """
+        from .base import Folder
+        from .collections import FolderCollection
+
+        if not args and set(kwargs) in ({"id"}, {"id", "changekey"}):
+            roots = {f.root for f in self.folder_collection.folders}
+            if len(roots) != 1:
+                raise ValueError(f"All folders must have the same root hierarchy ({roots})")
+            folders = list(
+                FolderCollection(
+                    account=self.folder_collection.account,
+                    folders=[
+                        Folder(
+                            _id=FolderId(**kwargs),
+                            root=roots.pop(),
+                        )
+                    ],
+                ).resolve()
+            )
+        elif args or kwargs:
+            folders = list(self.filter(*args, **kwargs))
+        else:
+            folders = list(self.all())
+        if not folders:
+            raise DoesNotExist("Could not find a child folder matching the query")
+        if len(folders) != 1:
+            raise MultipleObjectsReturned(f"Expected result length 1, but got {folders}")
+        f = folders[0]
+        if isinstance(f, Exception):
+            raise f
+        return f
+
+    def all(self):
+        """ """
+        new_qs = self._copy_self()
+        return new_qs
+
+    def filter(self, *args, **kwargs):
+        """Add restrictions to the folder search."""
+        new_qs = self._copy_self()
+        q = Q(*args, **kwargs)
+        new_qs.q = new_qs.q & q
+        return new_qs
+
+    def __iter__(self):
+        return self._query()
+
+    def _query(self):
+        from .base import Folder
+        from .collections import FolderCollection
+
+        if self.only_fields is None:
+            # Sub-folders will always be of class Folder
+            non_complex_fields = self.folder_collection.get_folder_fields(target_cls=Folder, is_complex=False)
+            complex_fields = self.folder_collection.get_folder_fields(target_cls=Folder, is_complex=True)
+        else:
+            non_complex_fields = {f for f in self.only_fields if not f.field.is_complex}
+            complex_fields = {f for f in self.only_fields if f.field.is_complex}
+
+        # First, fetch all non-complex fields using FindFolder. We do this because some folders do not support
+        # GetFolder, but we still want to get as much information as possible.
+        folders = self.folder_collection.find_folders(q=self.q, depth=self._depth, additional_fields=non_complex_fields)
+        if not complex_fields:
+            yield from folders
+            return
+
+        # Fetch all properties for the found folders
+        resolveable_folders = []
+        for f in folders:
+            if isinstance(f, Exception):
+                yield f
+                continue
+            if not f.get_folder_allowed:
+                log.debug("GetFolder not allowed on folder %s. Non-complex fields must be fetched with FindFolder", f)
+                yield f
+            else:
+                resolveable_folders.append(f)
+
+        # Get the complex fields using GetFolder, for the folders that support it, and add the extra field values
+        complex_folders = FolderCollection(
+            account=self.folder_collection.account, folders=resolveable_folders
+        ).get_folders(additional_fields=complex_fields)
+        for f, complex_f in zip(resolveable_folders, complex_folders):
+            if isinstance(f, MISSING_FOLDER_ERRORS):
+                # We were unlucky. The folder disappeared between the FindFolder and the GetFolder calls
+                continue
+            if isinstance(complex_f, Exception):
+                yield complex_f
+                continue
+            # Add the extra field values to the folders we fetched with find_folders()
+            if f.__class__ != complex_f.__class__:
+                raise ValueError(f"Type mismatch: {f} vs {complex_f}")
+            for complex_field in complex_fields:
+                field_name = complex_field.field.name
+                setattr(f, field_name, getattr(complex_f, field_name))
+            yield f
+
+
+class SingleFolderQuerySet(FolderQuerySet):
+    """A helper class with simpler argument types."""
+
+    def __init__(self, account, folder):
+        from .collections import FolderCollection
+
+        folder_collection = FolderCollection(account=account, folders=[folder])
+        super().__init__(folder_collection=folder_collection)
+
+    def _copy_cls(self):
+        return self.__class__(account=self.folder_collection.account, folder=self.folder_collection.folders[0])
+
+    def resolve(self):
+        return list(self.folder_collection.resolve())[0]

package/bin/_internal/exchangelib/folders/roots.py

@@ -0,0 +1,390 @@
+import logging
+from contextlib import suppress
+from threading import Lock
+
+from ..errors import ErrorAccessDenied, ErrorFolderNotFound, ErrorInvalidOperation
+from ..fields import EffectiveRightsField
+from ..properties import DistinguishedFolderId, EWSMeta, Mailbox
+from ..version import EXCHANGE_2007_SP1, EXCHANGE_2010_SP1
+from .base import BaseFolder
+from .collections import FolderCollection
+from .known_folders import (
+    MISC_FOLDERS,
+    NON_DELETABLE_FOLDERS,
+    WELLKNOWN_FOLDERS_IN_ARCHIVE_ROOT,
+    WELLKNOWN_FOLDERS_IN_ROOT,
+    MsgFolderRoot,
+)
+from .queryset import MISSING_FOLDER_ERRORS, SHALLOW, SingleFolderQuerySet
+
+log = logging.getLogger(__name__)
+
+
+class RootOfHierarchy(BaseFolder, metaclass=EWSMeta):
+    """Base class for folders that implement the root of a folder hierarchy."""
+
+    # A list of wellknown, or "distinguished", folders that are belong in this folder hierarchy. See
+    # https://docs.microsoft.com/en-us/dotnet/api/microsoft.exchange.webservices.data.wellknownfoldername
+    # and https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/distinguishedfolderid
+    # 'RootOfHierarchy' subclasses must not be in this list.
+    WELLKNOWN_FOLDERS = []
+
+    # This folder type also has 'folder:PermissionSet' on some server versions, but requesting it sometimes causes
+    # 'ErrorAccessDenied', as reported by some users. Ignore it entirely for root folders - it's usefulness is
+    # deemed minimal at best.
+    effective_rights = EffectiveRightsField(
+        field_uri="folder:EffectiveRights", is_read_only=True, supported_from=EXCHANGE_2007_SP1
+    )
+
+    __slots__ = "_account", "_subfolders", "_subfolders_lock"
+
+    # A special folder that acts as the top of a folder hierarchy. Finds and caches sub-folders at arbitrary depth.
+    def __init__(self, **kwargs):
+        self._account = kwargs.pop("account", None)  # A pointer back to the account holding the folder hierarchy
+        super().__init__(**kwargs)
+        self._subfolders = None  # See self._folders_map()
+        self._subfolders_lock = Lock()
+
+    @property
+    def account(self):
+        return self._account
+
+    @property
+    def root(self):
+        return self
+
+    @property
+    def parent(self):
+        return None
+
+    @classmethod
+    def register(cls, *args, **kwargs):
+        if cls is not RootOfHierarchy:
+            raise TypeError("For folder roots, custom fields must be registered on the RootOfHierarchy class")
+        return super().register(*args, **kwargs)
+
+    @classmethod
+    def deregister(cls, *args, **kwargs):
+        if cls is not RootOfHierarchy:
+            raise TypeError("For folder roots, custom fields must be registered on the RootOfHierarchy class")
+        return super().deregister(*args, **kwargs)
+
+    def get_folder(self, folder):
+        if not folder.id:
+            raise ValueError("'folder' must have an ID")
+        return self._folders_map.get(folder.id)
+
+    def add_folder(self, folder):
+        if not folder.id:
+            raise ValueError("'folder' must have an ID")
+        self._folders_map[folder.id] = folder
+
+    def update_folder(self, folder):
+        if not folder.id:
+            raise ValueError("'folder' must have an ID")
+        self._folders_map[folder.id] = folder
+
+    def remove_folder(self, folder):
+        if not folder.id:
+            raise ValueError("'folder' must have an ID")
+        with suppress(KeyError):
+            del self._folders_map[folder.id]
+
+    def clear_cache(self):
+        with self._subfolders_lock:
+            self._subfolders = None
+
+    def get_children(self, folder):
+        for f in self._folders_map.values():
+            if not f.parent:
+                continue
+            if f.parent.id == folder.id:
+                yield f
+
+    def get_default_folder(self, folder_cls):
+        """Return the distinguished folder instance of type folder_cls belonging to this account. If no distinguished
+        folder was found, try as best we can to return the default folder of type 'folder_cls'
+        """
+        if not folder_cls.DISTINGUISHED_FOLDER_ID:
+            raise ValueError(f"'folder_cls' {folder_cls} must have a DISTINGUISHED_FOLDER_ID value")
+        # Use cached distinguished folder instance, but only if cache has already been prepped. This is an optimization
+        # for accessing e.g. 'account.contacts' without fetching all folders of the account.
+        if self._subfolders is not None:
+            for f in self._folders_map.values():
+                # Require exact class, to not match subclasses, e.g. RecipientCache instead of Contacts
+                if f.__class__ == folder_cls and f.is_distinguished:
+                    log.debug("Found cached distinguished %s folder", folder_cls)
+                    return f
+        try:
+            log.debug("Requesting distinguished %s folder explicitly", folder_cls)
+            return folder_cls.get_distinguished(root=self)
+        except ErrorAccessDenied:
+            # Maybe we just don't have GetFolder access? Try FindItem instead
+            log.debug("Testing default %s folder with FindItem", folder_cls)
+            fld = folder_cls(
+                _distinguished_id=DistinguishedFolderId(
+                    id=folder_cls.DISTINGUISHED_FOLDER_ID,
+                    mailbox=Mailbox(email_address=self.account.primary_smtp_address),
+                ),
+                root=self,
+            )
+            fld.test_access()
+            return self._folders_map.get(fld.id, fld)  # Use cached instance if available
+        except MISSING_FOLDER_ERRORS:
+            # The Exchange server does not return a distinguished folder of this type
+            pass
+        raise ErrorFolderNotFound(f"No usable default {folder_cls} folders")
+
+    @classmethod
+    def get_distinguished(cls, account):
+        """Get the distinguished folder for this folder class.
+
+        :param account:
+        :return:
+        """
+        return cls._get_distinguished(
+            folder=cls(
+                _distinguished_id=DistinguishedFolderId(
+                    id=cls.DISTINGUISHED_FOLDER_ID,
+                    mailbox=Mailbox(email_address=account.primary_smtp_address),
+                ),
+                account=account,
+            )
+        )
+
+    @property
+    def _folders_map(self):
+        if self._subfolders is not None:
+            return self._subfolders
+
+        with self._subfolders_lock:
+            # Map root, and all sub-folders of root, at arbitrary depth by folder ID. First get distinguished folders,
+            # so we are sure to apply the correct Folder class, then fetch all sub-folders of this root.
+            folders_map = {self.id: self}
+            distinguished_folders = [
+                cls(
+                    _distinguished_id=DistinguishedFolderId(
+                        id=cls.DISTINGUISHED_FOLDER_ID,
+                        mailbox=Mailbox(email_address=self.account.primary_smtp_address),
+                    ),
+                    root=self,
+                )
+                for cls in self.WELLKNOWN_FOLDERS
+                if cls.get_folder_allowed and cls.supports_version(self.account.version)
+            ]
+            for f in FolderCollection(account=self.account, folders=distinguished_folders).resolve():
+                if isinstance(f, MISSING_FOLDER_ERRORS):
+                    # This is just a distinguished folder the server does not have
+                    continue
+                if isinstance(f, ErrorInvalidOperation):
+                    # This is probably a distinguished folder the server does not have. We previously tested the exact
+                    # error message (f.value), but some Exchange servers return localized error messages, so that's not
+                    # possible to do reliably.
+                    continue
+                if isinstance(f, ErrorAccessDenied):
+                    # We may not have GetFolder access, either to this folder or at all
+                    continue
+                if isinstance(f, Exception):
+                    raise f
+                folders_map[f.id] = f
+            for f in (
+                SingleFolderQuerySet(account=self.account, folder=self).depth(self.DEFAULT_FOLDER_TRAVERSAL_DEPTH).all()
+            ):
+                if isinstance(f, ErrorAccessDenied):
+                    # We may not have FindFolder access, or GetFolder access, either to this folder or at all
+                    continue
+                if isinstance(f, MISSING_FOLDER_ERRORS):
+                    # We were unlucky. The folder disappeared between the FindFolder and the GetFolder calls
+                    continue
+                if isinstance(f, Exception):
+                    raise f
+                if f.id in folders_map:
+                    # Already exists. Probably a distinguished folder
+                    continue
+                folders_map[f.id] = f
+            self._subfolders = folders_map
+            return folders_map
+
+    @classmethod
+    def from_xml(cls, elem, account):
+        kwargs = cls._kwargs_from_elem(elem=elem, account=account)
+        cls._clear(elem)
+        return cls(account=account, **kwargs)
+
+    @classmethod
+    def folder_cls_from_folder_name(cls, folder_name, folder_class, locale):
+        """Return the folder class that matches a localized folder name. Take into account the 'folder_class' of the
+        folder, to not identify an 'IPF.Note' folder as a 'Calendar' class just because it's called e.g. 'Kalender' and
+        the locale is 'da_DK'.
+
+        Some folders, e.g. `System`, don't define a `folder_class`. For these folders, we match on localized folder name
+        if the folder class does not have its 'CONTAINER_CLASS' set.
+
+        :param folder_name:
+        :param folder_class:
+        :param locale: a string, e.g. 'da_DK'
+        """
+        for folder_cls in cls.WELLKNOWN_FOLDERS + NON_DELETABLE_FOLDERS + MISC_FOLDERS:
+            if folder_cls.CONTAINER_CLASS != folder_class:
+                continue
+            if folder_name.lower() not in folder_cls.localized_names(locale):
+                continue
+            return folder_cls
+        raise KeyError()
+
+    def __getstate__(self):
+        # The lock cannot be pickled
+        state = {k: getattr(self, k) for k in self._slots_keys}
+        del state["_subfolders_lock"]
+        return state
+
+    def __setstate__(self, state):
+        # Restore the lock
+        for k in self._slots_keys:
+            setattr(self, k, state.get(k))
+        self._subfolders_lock = Lock()
+
+    def __repr__(self):
+        # Let's not create an infinite loop when printing self.root
+        return self.__class__.__name__ + repr(
+            (
+                self.account,
+                "[self]",
+                self.name,
+                self.total_count,
+                self.unread_count,
+                self.child_folder_count,
+                self.folder_class,
+                self.id,
+                self.changekey,
+            )
+        )
+
+
+class Root(RootOfHierarchy):
+    """The root of the standard folder hierarchy."""
+
+    DISTINGUISHED_FOLDER_ID = "root"
+    WELLKNOWN_FOLDERS = WELLKNOWN_FOLDERS_IN_ROOT
+
+    @property
+    def tois(self):
+        # 'Top of Information Store' is a folder available in some Exchange accounts. It usually contains the
+        # distinguished folders belonging to the account (inbox, calendar, trash etc.).
+        return self.get_default_folder(MsgFolderRoot)
+
+    def get_default_folder(self, folder_cls):
+        with suppress(MISSING_FOLDER_ERRORS):
+            return super().get_default_folder(folder_cls)
+
+        # Try to pick a suitable default folder. we do this by:
+        #  1. Searching the full folder list for a folder with the distinguished folder name
+        #  2. Searching TOIS for a direct child folder of the same type that is marked as distinguished
+        #  3. Searching TOIS for a direct child folder of the same type that has a localized name
+        #  4. Searching root for a direct child folder of the same type that is marked as distinguished
+        #  5. Searching root for a direct child folder of the same type that has a localized name
+        log.debug("Searching default %s folder in full folder list", folder_cls)
+
+        for f in self._folders_map.values():
+            # Require exact type, to avoid matching with subclasses (e.g. RecipientCache and Contacts)
+            if f.__class__ == folder_cls and f.has_distinguished_name:
+                log.debug("Found cached %s folder with default distinguished name", folder_cls)
+                return f
+
+        # Try direct children of TOIS first, unless we're trying to get the TOIS folder
+        if folder_cls != MsgFolderRoot:
+            with suppress(MISSING_FOLDER_ERRORS):
+                return self._get_candidate(folder_cls=folder_cls, folder_coll=self.tois.children)
+            # No candidates, or TOIS does not exist, or we don't have access to TOIS
+
+        # Finally, try direct children of root
+        return self._get_candidate(folder_cls=folder_cls, folder_coll=self.children)
+
+    def _get_candidate(self, folder_cls, folder_coll):
+        # Look for a single useful folder of type folder_cls in folder_coll
+        same_type = [f for f in folder_coll if f.__class__ == folder_cls]
+        are_distinguished = [f for f in same_type if f.is_distinguished]
+        if are_distinguished:
+            candidates = are_distinguished
+        else:
+            candidates = [f for f in same_type if f.name.lower() in folder_cls.localized_names(self.account.locale)]
+        if not candidates:
+            raise ErrorFolderNotFound(f"No usable default {folder_cls} folders")
+        if len(candidates) > 1:
+            raise ValueError(f"Multiple possible default {folder_cls} folders: {[f.name for f in candidates]}")
+        candidate = candidates[0]
+        if candidate.is_distinguished:
+            log.debug("Found distinguished %s folder", folder_cls)
+        else:
+            log.debug("Found %s folder with localized name %s", folder_cls, candidate.name)
+        return candidate
+
+
+class PublicFoldersRoot(RootOfHierarchy):
+    """The root of the public folder hierarchy. Not available on all mailboxes."""
+
+    DISTINGUISHED_FOLDER_ID = "publicfoldersroot"
+    DEFAULT_FOLDER_TRAVERSAL_DEPTH = SHALLOW
+    supported_from = EXCHANGE_2007_SP1
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        if self._distinguished_id:
+            self._distinguished_id.mailbox = None  # See DistinguishedFolderId.clean()
+
+    @property
+    def _folders_map(self):
+        # Top-level public folders may point to the root folder of the owning account and not the public folders root
+        # of this account. This breaks the assumption of get_children(). Fix it by overwriting the parent folder.
+        fix_parents = self._subfolders is None
+        res = super()._folders_map
+        if fix_parents:
+            with self._subfolders_lock:
+                for f in res.values():
+                    if f.id != self.id:
+                        f.parent = self
+        return res
+
+    def get_children(self, folder):
+        # EWS does not allow deep traversal of public folders, so self._folders_map will only populate the top-level
+        # subfolders. To traverse public folders at arbitrary depth, we need to get child folders on demand.
+
+        # Let's check if this folder already has any cached children. If so, assume we can just return those.
+        children = list(super().get_children(folder=folder))
+        if children:
+            # Return a generator like our parent does
+            yield from children
+            return
+
+        # Also return early if the server told us that there are no child folders.
+        if folder.child_folder_count == 0:
+            return
+
+        children_map = {}
+        with suppress(ErrorAccessDenied):
+            for f in (
+                SingleFolderQuerySet(account=self.account, folder=folder)
+                .depth(self.DEFAULT_FOLDER_TRAVERSAL_DEPTH)
+                .all()
+            ):
+                if isinstance(f, MISSING_FOLDER_ERRORS):
+                    # We were unlucky. The folder disappeared between the FindFolder and the GetFolder calls
+                    continue
+                if isinstance(f, Exception):
+                    raise f
+                children_map[f.id] = f
+
+        # Let's update the cache atomically, to avoid partial reads of the cache.
+        with self._subfolders_lock:
+            self._subfolders.update(children_map)
+
+        # Child folders have been cached now. Try super().get_children() again.
+        yield from super().get_children(folder=folder)
+
+
+class ArchiveRoot(RootOfHierarchy):
+    """The root of the archive folders hierarchy. Not available on all mailboxes."""
+
+    DISTINGUISHED_FOLDER_ID = "archiveroot"
+    supported_from = EXCHANGE_2010_SP1
+    WELLKNOWN_FOLDERS = WELLKNOWN_FOLDERS_IN_ARCHIVE_ROOT

package/bin/_internal/exchangelib/indexed_properties.py

@@ -0,0 +1,96 @@
+import logging
+
+from .fields import Choice, EmailSubField, LabelField, NamedSubField, SubField
+from .properties import EWSElement, EWSMeta
+
+log = logging.getLogger(__name__)
+
+
+class IndexedElement(EWSElement, metaclass=EWSMeta):
+    """Base class for all classes that implement an indexed element."""
+
+    LABEL_CHOICES = ()
+
+
+class SingleFieldIndexedElement(IndexedElement, metaclass=EWSMeta):
+    """Base class for all classes that implement an indexed element with a single field."""
+
+    @classmethod
+    def value_field(cls, version):
+        fields = cls.supported_fields(version=version)
+        if len(fields) != 1:
+            raise ValueError(f"Class {cls} must have only one value field (found {tuple(f.name for f in fields)})")
+        return fields[0]
+
+
+class EmailAddress(SingleFieldIndexedElement):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/entry-emailaddress"""
+
+    ELEMENT_NAME = "Entry"
+    LABEL_CHOICES = ("EmailAddress1", "EmailAddress2", "EmailAddress3")
+
+    label = LabelField(field_uri="Key", choices={Choice(c) for c in LABEL_CHOICES}, default=LABEL_CHOICES[0])
+    email = EmailSubField(is_required=True)
+
+
+class ImAddress(SingleFieldIndexedElement):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/entry-imaddress"""
+
+    ELEMENT_NAME = "Entry"
+    LABEL_CHOICES = ("ImAddress1", "ImAddress2", "ImAddress3")
+
+    label = LabelField(field_uri="Key", choices={Choice(c) for c in LABEL_CHOICES}, default=LABEL_CHOICES[0])
+    im_address = SubField(is_required=True)
+
+
+class PhoneNumber(SingleFieldIndexedElement):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/entry-phonenumber"""
+
+    ELEMENT_NAME = "Entry"
+    LABEL_CHOICES = (
+        "AssistantPhone",
+        "BusinessFax",
+        "BusinessPhone",
+        "BusinessPhone2",
+        "Callback",
+        "CarPhone",
+        "CompanyMainPhone",
+        "HomeFax",
+        "HomePhone",
+        "HomePhone2",
+        "Isdn",
+        "MobilePhone",
+        "OtherFax",
+        "OtherTelephone",
+        "Pager",
+        "PrimaryPhone",
+        "RadioPhone",
+        "Telex",
+        "TtyTddPhone",
+    )
+
+    label = LabelField(field_uri="Key", choices={Choice(c) for c in LABEL_CHOICES}, default="PrimaryPhone")
+    phone_number = SubField(is_required=True)
+
+
+class MultiFieldIndexedElement(IndexedElement, metaclass=EWSMeta):
+    """Base class for all classes that implement an indexed element with multiple fields."""
+
+
+class PhysicalAddress(MultiFieldIndexedElement):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/entry-physicaladdress"""
+
+    ELEMENT_NAME = "Entry"
+    LABEL_CHOICES = ("Business", "Home", "Other")
+
+    label = LabelField(field_uri="Key", choices={Choice(c) for c in LABEL_CHOICES}, default=LABEL_CHOICES[0])
+    street = NamedSubField(field_uri="Street")  # Street, house number, etc.
+    city = NamedSubField(field_uri="City")
+    state = NamedSubField(field_uri="State")
+    country = NamedSubField(field_uri="CountryOrRegion")
+    zipcode = NamedSubField(field_uri="PostalCode")
+
+    def clean(self, version=None):
+        if isinstance(self.zipcode, int):
+            self.zipcode = str(self.zipcode)
+        super().clean(version=version)