@backtomyfuture/exchange-cli-linux-arm64 0.1.10

package/bin/_internal/exchangelib/services/convert_id.py

@@ -0,0 +1,45 @@
+from ..errors import InvalidEnumValue, InvalidTypeError
+from ..properties import ID_FORMATS, AlternateId, AlternatePublicFolderId, AlternatePublicFolderItemId
+from ..util import create_element, set_xml_value
+from .common import EWSService
+
+
+class ConvertId(EWSService):
+    """Take a list of IDs to convert. Returns a list of converted IDs or exception instances, in the same order as the
+    input list.
+
+    MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/convertid-operation
+    """
+
+    SERVICE_NAME = "ConvertId"
+    cls_map = {cls.response_tag(): cls for cls in (AlternateId, AlternatePublicFolderId, AlternatePublicFolderItemId)}
+
+    def call(self, items, destination_format):
+        if destination_format not in ID_FORMATS:
+            raise InvalidEnumValue("destination_format", destination_format, ID_FORMATS)
+        return self._elems_to_objs(
+            self._chunked_get_elements(self.get_payload, items=items, destination_format=destination_format)
+        )
+
+    def _elem_to_obj(self, elem):
+        return self.cls_map[elem.tag].from_xml(elem, account=None)
+
+    def get_payload(self, items, destination_format):
+        supported_item_classes = AlternateId, AlternatePublicFolderId, AlternatePublicFolderItemId
+        payload = create_element(f"m:{self.SERVICE_NAME}", attrs=dict(DestinationFormat=destination_format))
+        item_ids = create_element("m:SourceIds")
+        for item in items:
+            if not isinstance(item, supported_item_classes):
+                raise InvalidTypeError("item", item, supported_item_classes)
+            set_xml_value(item_ids, item, version=None)
+        payload.append(item_ids)
+        return payload
+
+    @classmethod
+    def _get_elements_in_container(cls, container):
+        # We may have other elements in here, e.g. 'ResponseCode'. Filter away those.
+        return (
+            container.findall(AlternateId.response_tag())
+            + container.findall(AlternatePublicFolderId.response_tag())
+            + container.findall(AlternatePublicFolderItemId.response_tag())
+        )

package/bin/_internal/exchangelib/services/copy_item.py

@@ -0,0 +1,7 @@
+from . import move_item
+
+
+class CopyItem(move_item.MoveItem):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/copyitem-operation"""
+
+    SERVICE_NAME = "CopyItem"

package/bin/_internal/exchangelib/services/create_attachment.py

@@ -0,0 +1,34 @@
+from ..attachments import FileAttachment, ItemAttachment
+from ..items import BaseItem
+from ..properties import ParentItemId
+from ..util import MNS, create_element, set_xml_value
+from .common import EWSAccountService, to_item_id
+
+
+class CreateAttachment(EWSAccountService):
+    """MSDN:
+    https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createattachment-operation
+    """
+
+    SERVICE_NAME = "CreateAttachment"
+    element_container_name = f"{{{MNS}}}Attachments"
+    cls_map = {cls.response_tag(): cls for cls in (FileAttachment, ItemAttachment)}
+
+    def call(self, parent_item, items):
+        return self._elems_to_objs(self._chunked_get_elements(self.get_payload, items=items, parent_item=parent_item))
+
+    def _elem_to_obj(self, elem):
+        return self.cls_map[elem.tag].from_xml(elem=elem, account=self.account)
+
+    def get_payload(self, items, parent_item):
+        payload = create_element(f"m:{self.SERVICE_NAME}")
+        version = self.account.version
+        if isinstance(parent_item, BaseItem):
+            # to_item_id() would convert this to a normal ItemId, but the service wants a ParentItemId
+            parent_item = ParentItemId(parent_item.id, parent_item.changekey)
+        set_xml_value(payload, to_item_id(parent_item, ParentItemId), version=self.account.version)
+        attachments = create_element("m:Attachments")
+        for item in items:
+            set_xml_value(attachments, item, version=version)
+        payload.append(attachments)
+        return payload

package/bin/_internal/exchangelib/services/create_folder.py

@@ -0,0 +1,45 @@
+from ..errors import ErrorFolderExists
+from ..util import MNS, create_element
+from .common import EWSAccountService, folder_ids_element, parse_folder_elem, set_xml_value
+
+
+class CreateFolder(EWSAccountService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createfolder-operation"""
+
+    SERVICE_NAME = "CreateFolder"
+    element_container_name = f"{{{MNS}}}Folders"
+    ERRORS_TO_CATCH_IN_RESPONSE = EWSAccountService.ERRORS_TO_CATCH_IN_RESPONSE + (ErrorFolderExists,)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.folders = []  # A hack to communicate parsing args to _elems_to_objs()
+
+    def call(self, parent_folder, folders):
+        # We can't easily find the correct folder class from the returned XML. Instead, return objects with the same
+        # class as the folder instance it was requested with.
+        self.folders = list(folders)  # Convert to a list, in case 'folders' is a generator. We're iterating twice.
+        return self._elems_to_objs(
+            self._chunked_get_elements(
+                self.get_payload,
+                items=self.folders,
+                parent_folder=parent_folder,
+            )
+        )
+
+    def _elems_to_objs(self, elems):
+        for folder, elem in zip(self.folders, elems):
+            if isinstance(elem, Exception):
+                yield elem
+                continue
+            yield parse_folder_elem(elem=elem, folder=folder)
+
+    def get_payload(self, folders, parent_folder):
+        payload = create_element(f"m:{self.SERVICE_NAME}")
+        payload.append(
+            folder_ids_element(folders=[parent_folder], version=self.account.version, tag="m:ParentFolderId")
+        )
+        folder_elems = create_element("m:Folders")
+        for folder in folders:
+            set_xml_value(folder_elems, folder, version=self.account.version)
+        payload.append(folder_elems)
+        return payload

package/bin/_internal/exchangelib/services/create_item.py

@@ -0,0 +1,97 @@
+from ..errors import InvalidEnumValue, InvalidTypeError
+from ..folders import BaseFolder
+from ..items import (
+    MESSAGE_DISPOSITION_CHOICES,
+    SAVE_ONLY,
+    SEND_AND_SAVE_COPY,
+    SEND_MEETING_INVITATIONS_CHOICES,
+    SEND_ONLY,
+    BulkCreateResult,
+)
+from ..properties import FolderId
+from ..util import MNS, create_element, set_xml_value
+from .common import EWSAccountService, folder_ids_element
+
+
+class CreateItem(EWSAccountService):
+    """Take a folder and a list of items. Return the result of creation as a list of tuples (success[True|False],
+    errormessage), in the same order as the input list.
+
+    MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createitem-operation
+    """
+
+    SERVICE_NAME = "CreateItem"
+    element_container_name = f"{{{MNS}}}Items"
+
+    def call(self, items, folder, message_disposition, send_meeting_invitations):
+        if message_disposition not in MESSAGE_DISPOSITION_CHOICES:
+            raise InvalidEnumValue("message_disposition", message_disposition, MESSAGE_DISPOSITION_CHOICES)
+        if send_meeting_invitations not in SEND_MEETING_INVITATIONS_CHOICES:
+            raise InvalidEnumValue(
+                "send_meeting_invitations", send_meeting_invitations, SEND_MEETING_INVITATIONS_CHOICES
+            )
+        if folder is not None:
+            if not isinstance(folder, (BaseFolder, FolderId)):
+                raise InvalidTypeError("folder", folder, (BaseFolder, FolderId))
+            if folder.account != self.account:
+                raise ValueError("Folder must belong to account")
+        if message_disposition == SAVE_ONLY and folder is None:
+            raise AttributeError("Folder must be supplied when in save-only mode")
+        if message_disposition == SEND_AND_SAVE_COPY and folder is None:
+            folder = self.account.sent  # 'Sent' is default EWS behaviour
+        if message_disposition == SEND_ONLY and folder is not None:
+            raise AttributeError("Folder must be None in send-ony mode")
+        return self._elems_to_objs(
+            self._chunked_get_elements(
+                self.get_payload,
+                items=items,
+                folder=folder,
+                message_disposition=message_disposition,
+                send_meeting_invitations=send_meeting_invitations,
+            )
+        )
+
+    def _elem_to_obj(self, elem):
+        if isinstance(elem, bool):
+            return elem
+        return BulkCreateResult.from_xml(elem=elem, account=self.account)
+
+    @classmethod
+    def _get_elements_in_container(cls, container):
+        res = super()._get_elements_in_container(container)
+        return res or [True]
+
+    def get_payload(self, items, folder, message_disposition, send_meeting_invitations):
+        """Take a list of Item objects (CalendarItem, Message etc.) and return the XML for a CreateItem request.
+        convert items to XML Elements.
+
+        MessageDisposition is only applicable to email messages, where it is required.
+
+        SendMeetingInvitations is required for calendar items. It is also applicable to tasks, meeting request
+        responses (see
+        https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createitem-operation-meeting-request
+        ) and sharing
+        invitation accepts (see
+        https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createitem-acceptsharinginvitation
+        ). The last two are not supported yet.
+
+        :param items:
+        :param folder:
+        :param message_disposition:
+        :param send_meeting_invitations:
+        """
+        payload = create_element(
+            f"m:{self.SERVICE_NAME}",
+            attrs=dict(MessageDisposition=message_disposition, SendMeetingInvitations=send_meeting_invitations),
+        )
+        if folder:
+            payload.append(
+                folder_ids_element(folders=[folder], version=self.account.version, tag="m:SavedItemFolderId")
+            )
+        item_elems = create_element("m:Items")
+        for item in items:
+            if not item.account:
+                item.account = self.account
+            set_xml_value(item_elems, item, version=self.account.version)
+        payload.append(item_elems)
+        return payload

package/bin/_internal/exchangelib/services/create_user_configuration.py

@@ -0,0 +1,19 @@
+from ..util import create_element, set_xml_value
+from .common import EWSAccountService
+
+
+class CreateUserConfiguration(EWSAccountService):
+    """MSDN:
+    https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/createuserconfiguration-operation
+    """
+
+    SERVICE_NAME = "CreateUserConfiguration"
+    returns_elements = False
+
+    def call(self, user_configuration):
+        return self._get_elements(payload=self.get_payload(user_configuration=user_configuration))
+
+    def get_payload(self, user_configuration):
+        return set_xml_value(
+            create_element(f"m:{self.SERVICE_NAME}"), user_configuration, version=self.protocol.version
+        )

package/bin/_internal/exchangelib/services/delete_attachment.py

@@ -0,0 +1,28 @@
+from ..properties import RootItemId
+from ..util import create_element, set_xml_value
+from .common import EWSAccountService, attachment_ids_element
+
+
+class DeleteAttachment(EWSAccountService):
+    """MSDN:
+    https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/deleteattachment-operation
+    """
+
+    SERVICE_NAME = "DeleteAttachment"
+
+    def call(self, items):
+        return self._elems_to_objs(self._chunked_get_elements(self.get_payload, items=items))
+
+    def _elem_to_obj(self, elem):
+        return RootItemId.from_xml(elem=elem, account=self.account)
+
+    @classmethod
+    def _get_elements_in_container(cls, container):
+        return container.findall(RootItemId.response_tag())
+
+    def get_payload(self, items):
+        return set_xml_value(
+            create_element(f"m:{self.SERVICE_NAME}"),
+            attachment_ids_element(items=items, version=self.account.version),
+            version=self.account.version,
+        )

package/bin/_internal/exchangelib/services/delete_folder.py

@@ -0,0 +1,21 @@
+from ..errors import InvalidEnumValue
+from ..items import DELETE_TYPE_CHOICES
+from ..util import create_element
+from .common import EWSAccountService, folder_ids_element
+
+
+class DeleteFolder(EWSAccountService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/deletefolder-operation"""
+
+    SERVICE_NAME = "DeleteFolder"
+    returns_elements = False
+
+    def call(self, folders, delete_type):
+        if delete_type not in DELETE_TYPE_CHOICES:
+            raise InvalidEnumValue("delete_type", delete_type, DELETE_TYPE_CHOICES)
+        return self._chunked_get_elements(self.get_payload, items=folders, delete_type=delete_type)
+
+    def get_payload(self, folders, delete_type):
+        payload = create_element(f"m:{self.SERVICE_NAME}", attrs=dict(DeleteType=delete_type))
+        payload.append(folder_ids_element(folders=folders, version=self.account.version))
+        return payload

package/bin/_internal/exchangelib/services/delete_item.py

@@ -0,0 +1,51 @@
+from ..errors import InvalidEnumValue
+from ..items import AFFECTED_TASK_OCCURRENCES_CHOICES, DELETE_TYPE_CHOICES, SEND_MEETING_CANCELLATIONS_CHOICES
+from ..util import create_element
+from ..version import EXCHANGE_2013_SP1
+from .common import EWSAccountService, item_ids_element
+
+
+class DeleteItem(EWSAccountService):
+    """Take a folder and a list of (id, changekey) tuples. Return result of deletion as a list of tuples
+    (success[True|False], errormessage), in the same order as the input list.
+
+    MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/deleteitem-operation
+    """
+
+    SERVICE_NAME = "DeleteItem"
+    returns_elements = False
+
+    def call(self, items, delete_type, send_meeting_cancellations, affected_task_occurrences, suppress_read_receipts):
+        if delete_type not in DELETE_TYPE_CHOICES:
+            raise InvalidEnumValue("delete_type", delete_type, DELETE_TYPE_CHOICES)
+        if send_meeting_cancellations not in SEND_MEETING_CANCELLATIONS_CHOICES:
+            raise InvalidEnumValue(
+                "send_meeting_cancellations", send_meeting_cancellations, SEND_MEETING_CANCELLATIONS_CHOICES
+            )
+        if affected_task_occurrences not in AFFECTED_TASK_OCCURRENCES_CHOICES:
+            raise InvalidEnumValue(
+                "affected_task_occurrences", affected_task_occurrences, AFFECTED_TASK_OCCURRENCES_CHOICES
+            )
+        return self._chunked_get_elements(
+            self.get_payload,
+            items=items,
+            delete_type=delete_type,
+            send_meeting_cancellations=send_meeting_cancellations,
+            affected_task_occurrences=affected_task_occurrences,
+            suppress_read_receipts=suppress_read_receipts,
+        )
+
+    def get_payload(
+        self, items, delete_type, send_meeting_cancellations, affected_task_occurrences, suppress_read_receipts
+    ):
+        # Takes a list of (id, changekey) tuples or Item objects and returns the XML for a DeleteItem request.
+        attrs = dict(
+            DeleteType=delete_type,
+            SendMeetingCancellations=send_meeting_cancellations,
+            AffectedTaskOccurrences=affected_task_occurrences,
+        )
+        if self.account.version.build >= EXCHANGE_2013_SP1:
+            attrs["SuppressReadReceipts"] = suppress_read_receipts
+        payload = create_element(f"m:{self.SERVICE_NAME}", attrs=attrs)
+        payload.append(item_ids_element(items=items, version=self.account.version))
+        return payload

package/bin/_internal/exchangelib/services/delete_user_configuration.py

@@ -0,0 +1,19 @@
+from ..util import create_element, set_xml_value
+from .common import EWSAccountService
+
+
+class DeleteUserConfiguration(EWSAccountService):
+    """MSDN:
+    https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/deleteuserconfiguration-operation
+    """
+
+    SERVICE_NAME = "DeleteUserConfiguration"
+    returns_elements = False
+
+    def call(self, user_configuration_name):
+        return self._get_elements(payload=self.get_payload(user_configuration_name=user_configuration_name))
+
+    def get_payload(self, user_configuration_name):
+        return set_xml_value(
+            create_element(f"m:{self.SERVICE_NAME}"), user_configuration_name, version=self.account.version
+        )

package/bin/_internal/exchangelib/services/empty_folder.py

@@ -0,0 +1,25 @@
+from ..errors import InvalidEnumValue
+from ..items import DELETE_TYPE_CHOICES
+from ..util import create_element
+from .common import EWSAccountService, folder_ids_element
+
+
+class EmptyFolder(EWSAccountService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/emptyfolder-operation"""
+
+    SERVICE_NAME = "EmptyFolder"
+    returns_elements = False
+
+    def call(self, folders, delete_type, delete_sub_folders):
+        if delete_type not in DELETE_TYPE_CHOICES:
+            raise InvalidEnumValue("delete_type", delete_type, DELETE_TYPE_CHOICES)
+        return self._chunked_get_elements(
+            self.get_payload, items=folders, delete_type=delete_type, delete_sub_folders=delete_sub_folders
+        )
+
+    def get_payload(self, folders, delete_type, delete_sub_folders):
+        payload = create_element(
+            f"m:{self.SERVICE_NAME}", attrs=dict(DeleteType=delete_type, DeleteSubFolders=delete_sub_folders)
+        )
+        payload.append(folder_ids_element(folders=folders, version=self.account.version))
+        return payload

package/bin/_internal/exchangelib/services/expand_dl.py

@@ -0,0 +1,21 @@
+from ..errors import ErrorNameResolutionMultipleResults
+from ..properties import Mailbox
+from ..util import MNS, create_element, set_xml_value
+from .common import EWSService
+
+
+class ExpandDL(EWSService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/expanddl-operation"""
+
+    SERVICE_NAME = "ExpandDL"
+    element_container_name = f"{{{MNS}}}DLExpansion"
+    WARNINGS_TO_IGNORE_IN_RESPONSE = ErrorNameResolutionMultipleResults
+
+    def call(self, distribution_list):
+        return self._elems_to_objs(self._get_elements(payload=self.get_payload(distribution_list=distribution_list)))
+
+    def _elem_to_obj(self, elem):
+        return Mailbox.from_xml(elem, account=None)
+
+    def get_payload(self, distribution_list):
+        return set_xml_value(create_element(f"m:{self.SERVICE_NAME}"), distribution_list, version=self.protocol.version)

package/bin/_internal/exchangelib/services/export_items.py

@@ -0,0 +1,27 @@
+from ..errors import ResponseMessageError
+from ..util import MNS, create_element
+from .common import EWSAccountService, item_ids_element
+
+
+class ExportItems(EWSAccountService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/exportitems-operation"""
+
+    ERRORS_TO_CATCH_IN_RESPONSE = ResponseMessageError
+    SERVICE_NAME = "ExportItems"
+    element_container_name = f"{{{MNS}}}Data"
+
+    def call(self, items):
+        return self._elems_to_objs(self._chunked_get_elements(self.get_payload, items=items))
+
+    def _elem_to_obj(self, elem):
+        return elem.text  # All we want is the 64bit string in the 'Data' tag
+
+    def get_payload(self, items):
+        payload = create_element(f"m:{self.SERVICE_NAME}")
+        payload.append(item_ids_element(items=items, version=self.account.version))
+        return payload
+
+    # We need to override this since ExportItemsResponseMessage is formatted a bit differently.
+    @classmethod
+    def _get_elements_in_container(cls, container):
+        return [container]

package/bin/_internal/exchangelib/services/find_folder.py

@@ -0,0 +1,80 @@
+from ..errors import InvalidEnumValue
+from ..folders import Folder
+from ..folders.queryset import FOLDER_TRAVERSAL_CHOICES
+from ..items import SHAPE_CHOICES
+from ..util import MNS, TNS, create_element
+from ..version import EXCHANGE_2010
+from .common import EWSPagingService, folder_ids_element, shape_element
+
+
+class FindFolder(EWSPagingService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/findfolder-operation"""
+
+    SERVICE_NAME = "FindFolder"
+    element_container_name = f"{{{TNS}}}Folders"
+    paging_container_name = f"{{{MNS}}}RootFolder"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.root = None  # A hack to communicate parsing args to _elems_to_objs()
+
+    def call(self, folders, additional_fields, restriction, shape, depth, max_items, offset):
+        """Find sub-folders of a folder.
+
+        :param folders: the folders to act on
+        :param additional_fields: the extra fields that should be returned with the folder, as FieldPath objects
+        :param restriction: Restriction object that defines the filters for the query
+        :param shape: The set of attributes to return
+        :param depth: How deep in the folder structure to search for folders
+        :param max_items: The maximum number of items to return
+        :param offset: the offset relative to the first item in the item collection. Usually 0.
+
+        :return: XML elements for the matching folders
+        """
+        if shape not in SHAPE_CHOICES:
+            raise InvalidEnumValue("shape", shape, SHAPE_CHOICES)
+        if depth not in FOLDER_TRAVERSAL_CHOICES:
+            raise InvalidEnumValue("depth", depth, FOLDER_TRAVERSAL_CHOICES)
+        roots = {f.root for f in folders}
+        if len(roots) != 1:
+            raise ValueError(f"All folders must have the same root hierarchy ({roots})")
+        self.root = roots.pop()
+        return self._elems_to_objs(
+            self._paged_call(
+                payload_func=self.get_payload,
+                max_items=max_items,
+                folders=folders,
+                **dict(
+                    additional_fields=additional_fields,
+                    restriction=restriction,
+                    shape=shape,
+                    depth=depth,
+                    page_size=self.page_size,
+                    offset=offset,
+                ),
+            )
+        )
+
+    def _elem_to_obj(self, elem):
+        return Folder.from_xml_with_root(elem=elem, root=self.root)
+
+    def get_payload(self, folders, additional_fields, restriction, shape, depth, page_size, offset=0):
+        payload = create_element(f"m:{self.SERVICE_NAME}", attrs=dict(Traversal=depth))
+        payload.append(
+            shape_element(
+                tag="m:FolderShape", shape=shape, additional_fields=additional_fields, version=self.account.version
+            )
+        )
+        if self.account.version.build >= EXCHANGE_2010:
+            indexed_page_folder_view = create_element(
+                "m:IndexedPageFolderView",
+                attrs=dict(MaxEntriesReturned=page_size, Offset=offset, BasePoint="Beginning"),
+            )
+            payload.append(indexed_page_folder_view)
+        else:
+            if offset != 0:
+                raise NotImplementedError("'offset' is only supported for Exchange 2010 servers and later")
+        if restriction:
+            payload.append(restriction.to_xml(version=self.account.version))
+        payload.append(folder_ids_element(folders=folders, version=self.protocol.version, tag="m:ParentFolderIds"))
+        return payload

package/bin/_internal/exchangelib/services/find_item.py

@@ -0,0 +1,112 @@
+from ..errors import InvalidEnumValue
+from ..folders.base import BaseFolder
+from ..items import ID_ONLY, ITEM_TRAVERSAL_CHOICES, SHAPE_CHOICES, Item
+from ..util import MNS, TNS, create_element, set_xml_value
+from .common import EWSPagingService, folder_ids_element, shape_element
+
+
+class FindItem(EWSPagingService):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/finditem-operation"""
+
+    SERVICE_NAME = "FindItem"
+    element_container_name = f"{{{TNS}}}Items"
+    paging_container_name = f"{{{MNS}}}RootFolder"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # A hack to communicate parsing args to _elems_to_objs()
+        self.additional_fields = None
+        self.shape = None
+
+    def call(
+        self,
+        folders,
+        additional_fields,
+        restriction,
+        order_fields,
+        shape,
+        query_string,
+        depth,
+        calendar_view,
+        max_items,
+        offset,
+    ):
+        """Find items in an account.
+
+        :param folders: the folders to act on
+        :param additional_fields: the extra fields that should be returned with the item, as FieldPath objects
+        :param restriction: a Restriction object for
+        :param order_fields: the fields to sort the results by
+        :param shape: The set of attributes to return
+        :param query_string: a QueryString object
+        :param depth: How deep in the folder structure to search for items
+        :param calendar_view: If set, returns recurring calendar items unfolded
+        :param max_items: the max number of items to return
+        :param offset: the offset relative to the first item in the item collection. Usually 0.
+
+        :return: XML elements for the matching items
+        """
+        if shape not in SHAPE_CHOICES:
+            raise InvalidEnumValue("shape", shape, SHAPE_CHOICES)
+        if depth not in ITEM_TRAVERSAL_CHOICES:
+            raise InvalidEnumValue("depth", depth, ITEM_TRAVERSAL_CHOICES)
+        self.additional_fields = additional_fields
+        self.shape = shape
+        return self._elems_to_objs(
+            self._paged_call(
+                payload_func=self.get_payload,
+                max_items=max_items,
+                folders=folders,
+                **dict(
+                    additional_fields=additional_fields,
+                    restriction=restriction,
+                    order_fields=order_fields,
+                    query_string=query_string,
+                    shape=shape,
+                    depth=depth,
+                    calendar_view=calendar_view,
+                    page_size=self.page_size,
+                    offset=offset,
+                ),
+            )
+        )
+
+    def _elem_to_obj(self, elem):
+        if self.shape == ID_ONLY and self.additional_fields is None:
+            return Item.id_from_xml(elem)
+        return BaseFolder.item_model_from_tag(elem.tag).from_xml(elem=elem, account=self.account)
+
+    def get_payload(
+        self,
+        folders,
+        additional_fields,
+        restriction,
+        order_fields,
+        query_string,
+        shape,
+        depth,
+        calendar_view,
+        page_size,
+        offset=0,
+    ):
+        payload = create_element(f"m:{self.SERVICE_NAME}", attrs=dict(Traversal=depth))
+        payload.append(
+            shape_element(
+                tag="m:ItemShape", shape=shape, additional_fields=additional_fields, version=self.account.version
+            )
+        )
+        if calendar_view is None:
+            view_type = create_element(
+                "m:IndexedPageItemView", attrs=dict(MaxEntriesReturned=page_size, Offset=offset, BasePoint="Beginning")
+            )
+        else:
+            view_type = calendar_view.to_xml(version=self.account.version)
+        payload.append(view_type)
+        if restriction:
+            payload.append(restriction.to_xml(version=self.account.version))
+        if order_fields:
+            payload.append(set_xml_value(create_element("m:SortOrder"), order_fields, version=self.account.version))
+        payload.append(folder_ids_element(folders=folders, version=self.protocol.version, tag="m:ParentFolderIds"))
+        if query_string:
+            payload.append(query_string.to_xml(version=self.account.version))
+        return payload