Office365-REST-Python-Client 2.5.10__py3-none-any.whl → 2.5.11__py3-none-any.whl

office365/directory/policies/root.py

@@ -1,3 +1,4 @@
+from office365.directory.policies.admin_consent_request import AdminConsentRequestPolicy
 from office365.directory.policies.app_management import AppManagementPolicy
 from office365.directory.policies.authentication_flows import AuthenticationFlowsPolicy
 from office365.directory.policies.authentication_methods import (
@@ -20,6 +21,19 @@ from office365.runtime.paths.resource_path import ResourcePath
 class PolicyRoot(Entity):
     """Resource type exposing navigation properties for the policies singleton."""
 
+    @property
+    def admin_consent_request_policy(self):
+        """
+        The policy by which consent requests are created and managed for the entire tenant.
+        """
+        return self.properties.get(
+            "adminConsentRequestPolicy",
+            AdminConsentRequestPolicy(
+                self.context,
+                ResourcePath("adminConsentRequestPolicy", self.resource_path),
+            ),
+        )
+
     @property
     def authentication_methods_policy(self):
         """
@@ -151,6 +165,7 @@ class PolicyRoot(Entity):
     def get_property(self, name, default_value=None):
         if default_value is None:
             property_mapping = {
+                "adminConsentRequestPolicy": self.admin_consent_request_policy,
                 "authenticationStrengthPolicies": self.authentication_strength_policies,
                 "authenticationFlowsPolicy": self.authentication_flows_policy,
                 "appManagementPolicies": self.app_management_policies,

office365/directory/synchronization/status.py

@@ -1,5 +1,8 @@
 from office365.directory.synchronization.progress import SynchronizationProgress
 from office365.directory.synchronization.quarantine import SynchronizationQuarantine
+from office365.directory.synchronization.task_execution import (
+    SynchronizationTaskExecution,
+)
 from office365.runtime.client_value import ClientValue
 from office365.runtime.client_value_collection import ClientValueCollection
 
@@ -7,10 +10,20 @@ from office365.runtime.client_value_collection import ClientValueCollection
 class SynchronizationStatus(ClientValue):
     """Represents the current status of the synchronizationJob."""
 
-    def __init__(self, progress=None, quarantine=SynchronizationQuarantine()):
+    def __init__(
+        self,
+        progress=None,
+        quarantine=SynchronizationQuarantine(),
+        last_execution=SynchronizationTaskExecution(),
+        last_successful_execution=SynchronizationTaskExecution(),
+        last_successful_execution_with_exports=SynchronizationTaskExecution(),
+    ):
         """
         :param list[SynchronizationProgress] progress: Details of the progress of a job toward completion.
         :param SynchronizationQuarantine quarantine:
         """
         self.progress = ClientValueCollection(SynchronizationProgress, progress)
         self.quarantine = quarantine
+        self.lastExecution = last_execution
+        self.lastSuccessfulExecution = last_successful_execution
+        self.lastSuccessfulExecutionWithExports = last_successful_execution_with_exports

office365/directory/synchronization/task_execution.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class SynchronizationTaskExecution(ClientValue):
+    """Summarizes the results of the synchronization job run."""

office365/directory/users/user.py

@@ -1,6 +1,6 @@
 import json
 from datetime import datetime
-from typing import Optional
+from typing import List, Optional
 
 from office365.communications.onlinemeetings.collection import OnlineMeetingCollection
 from office365.communications.presences.presence import Presence
@@ -46,6 +46,7 @@ from office365.outlook.contacts.collection import ContactCollection
 from office365.outlook.contacts.folder import ContactFolder
 from office365.outlook.convert_id_result import ConvertIdResult
 from office365.outlook.mail.folders.collection import MailFolderCollection
+from office365.outlook.mail.item_body import ItemBody
 from office365.outlook.mail.mailbox_settings import MailboxSettings
 from office365.outlook.mail.messages.collection import MessageCollection
 from office365.outlook.mail.messages.message import Message
@@ -201,6 +202,7 @@ class User(DirectoryObject):
         bcc_recipients=None,
         save_to_sent_items=False,
     ):
+        # type: (str, str|ItemBody, List[str], List[str], List[str], bool) -> Message
         """Send a new message on the fly
 
         :param str subject: The subject of the message.
@@ -347,7 +349,7 @@ class User(DirectoryObject):
                 start_dt.isoformat(), end_dt.isoformat()
             )
 
-        self.context.add_query(qry).before_execute(_construct_request)
+        self.context.add_query(qry).before_query_execute(_construct_request)
         return return_type
 
     def get_reminder_view(self, start_dt, end_dt):

office365/graph_client.py

@@ -41,6 +41,7 @@ from office365.directory.users.collection import UserCollection
 from office365.directory.users.user import User
 from office365.education.root import EducationRoot
 from office365.entity_collection import EntityCollection
+from office365.graph_request import GraphRequest
 from office365.intune.devices.app_management import DeviceAppManagement
 from office365.intune.devices.collection import DeviceCollection
 from office365.intune.devices.management.management import DeviceManagement
@@ -58,7 +59,6 @@ from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
-from office365.runtime.odata.request import ODataRequest
 from office365.runtime.odata.v4.batch_request import ODataV4BatchRequest
 from office365.runtime.odata.v4.json_format import V4JsonFormat
 from office365.runtime.paths.resource_path import ResourcePath
@@ -73,31 +73,14 @@ from office365.teams.collection import TeamCollection
 from office365.teams.template import TeamsTemplate
 from office365.teams.viva.employee_experience import EmployeeExperience
 
-environments_endpoints = {
-    "GCCH": {
-        "graph_url": "https://graph.microsoft.com",
-        "entra_url": "https://login.microsoftonline.com",
-    },
-    "GCC High": {
-        "graph_url": "https://graph.microsoft.us",
-        "entra_url": "https://login.microsoftonline.us",
-    },
-    "DoD": {
-        "graph_url": "https://dod-graph.microsoft.us",
-        "entra_url": "https://login.chinacloudapi.cn",
-    },
-}
-
 
 class GraphClient(ClientRuntimeContext):
     """Graph Service client"""
 
-    def __init__(self, acquire_token_callback, version="v1.0", environment="GCCH"):
-        # type: (Callable[[], dict], str, str) -> None
+    def __init__(self, acquire_token_callback):
+        # type: (Callable[[], dict]) -> None
         super(GraphClient, self).__init__()
         self._pending_request = None
-        self._version = version
-        self._environment_endpoints = environments_endpoints.get(environment, None)
         self._acquire_token_callback = acquire_token_callback
 
     @staticmethod
@@ -127,7 +110,7 @@ class GraphClient(ClientRuntimeContext):
                 "thumbprint": thumbprint,
                 "private_key": private_key,
             },
-            token_cache=token_cache  # Default cache is in memory only.
+            token_cache=token_cache,  # Default cache is in memory only.
             # You can learn how to use SerializableTokenCache from
             # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
         )
@@ -259,16 +242,16 @@ class GraphClient(ClientRuntimeContext):
         return self
 
     def pending_request(self):
-        # type: () -> ODataRequest
+        # type: () -> GraphRequest
         if self._pending_request is None:
-            self._pending_request = ODataRequest(V4JsonFormat())
+            self._pending_request = GraphRequest()
             self._pending_request.beforeExecute += self._authenticate_request
             self._pending_request.beforeExecute += self._build_specific_query
         return self._pending_request
 
     def service_root_url(self):
         # type: () -> str
-        return "https://graph.microsoft.com/{0}".format(self._version)
+        return self.pending_request().service_root_url
 
     def _build_specific_query(self, request):
         # type: (RequestOptions) -> None

office365/graph_request.py

@@ -1,7 +1,30 @@
 from office365.runtime.odata.request import ODataRequest
 from office365.runtime.odata.v4.json_format import V4JsonFormat
 
+environments_endpoints = {
+    "GCCH": {
+        "graph_url": "https://graph.microsoft.com",
+        "entra_url": "https://login.microsoftonline.com",
+    },
+    "GCC High": {
+        "graph_url": "https://graph.microsoft.us",
+        "entra_url": "https://login.microsoftonline.us",
+    },
+    "DoD": {
+        "graph_url": "https://dod-graph.microsoft.us",
+        "entra_url": "https://login.chinacloudapi.cn",
+    },
+}
+
 
 class GraphRequest(ODataRequest):
-    def __init__(self):
+    def __init__(self, version="v1.0", environment="GCCH"):
+        # type: (str, str) -> None
         super(GraphRequest, self).__init__(V4JsonFormat())
+        self._version = version
+        self._environment_endpoints = environments_endpoints.get(environment, None)
+
+    @property
+    def service_root_url(self):
+        # type: () -> str
+        return "https://graph.microsoft.com/{0}".format(self._version)

office365/onedrive/driveitems/driveItem.py

@@ -469,6 +469,7 @@ class DriveItem(BaseItem):
         return self.get_content(format_name)
 
     def copy(self, name=None, parent=None, conflict_behavior=ConflictBehavior.Fail):
+        # type: (str, ItemReference|"DriveItem", str) -> ClientResult[str]
         """Asynchronously creates a copy of an driveItem (including any children), under a new parent item or with a
         new name.
 
@@ -480,32 +481,30 @@ class DriveItem(BaseItem):
 
         Returns location for details about how to monitor the progress of the copy, upon accepting the request.
         """
-        return_type = ClientResult(self.context)  # type: ClientResult[str]
+        return_type = ClientResult(self.context, str())
 
-        def _create_request(request):
-            # type: (RequestOptions) -> None
-            request.url += "?@microsoft.graph.conflictBehavior={0}".format(
-                conflict_behavior
-            )
+        def _copy(parent_reference):
+            # type: (ItemReference) -> None
+
+            def _create_request(request):
+                # type: (RequestOptions) -> None
+                request.url += "?@microsoft.graph.conflictBehavior={0}".format(
+                    conflict_behavior
+                )
+
+            def _process_response(resp):
+                # type: (requests.Response) -> None
+                resp.raise_for_status()
+                location = resp.headers.get("Location", None)
+                if location is None:
+                    return
+                return_type.set_property("__value", location)
 
-        def _process_response(resp):
-            # type: (requests.Response) -> None
-            resp.raise_for_status()
-            location = resp.headers.get("Location", None)
-            if location is None:
-                return
-            return_type.set_property("__value", location)
-
-        def _create_and_add_query(parent_reference):
-            """
-            :param office365.onedrive.listitems.item_reference.ItemReference or None parent_reference:  Reference to the
-             parent item the copy will be created in.
-            """
             payload = {"name": name, "parentReference": parent_reference}
-            self.context.before_execute(_create_request)
-            self.context.after_execute(_process_response)
             qry = ServiceOperationQuery(self, "copy", None, payload, None, return_type)
-            self.context.add_query(qry)
+            self.context.add_query(qry).before_query_execute(
+                _create_request
+            ).after_execute(_process_response)
 
         if isinstance(parent, DriveItem):
 
@@ -513,14 +512,15 @@ class DriveItem(BaseItem):
                 parent_reference = ItemReference(
                     drive_id=parent.parent_reference.driveId, _id=parent.id
                 )
-                _create_and_add_query(parent_reference)
+                _copy(parent_reference)
 
             parent.ensure_property("parentReference", _drive_item_loaded)
         else:
-            _create_and_add_query(parent)
+            _copy(parent)
         return return_type
 
-    def move(self, name=None, parent=None):
+    def move(self, name=None, parent=None, conflict_behavior=ConflictBehavior.Fail):
+        # type: (str, ItemReference|"DriveItem", str) -> "DriveItem"
         """To move a DriveItem to a new parent item, your app requests to update the parentReference of the DriveItem
         to move.
 
@@ -528,29 +528,34 @@ class DriveItem(BaseItem):
              original.
         :param ItemReference or DriveItem or None parent: Reference to the
              parent item the move will be created in.
+        :param str conflict_behavior: query parameter to customize the behavior when a conflict occurs.
         """
 
-        return_type = ClientResult(self.context, str())
+        return_type = DriveItem(self.context)
+        self.children.add_child(return_type)
 
-        def _create_and_add_query(parent_reference):
+        def _move(parent_reference):
+            # type: (ItemReference) -> None
             payload = {"name": name, "parentReference": parent_reference}
 
             def _construct_request(request):
                 # type: (RequestOptions) -> None
                 request.method = HttpMethod.Patch
+                request.url += "?@microsoft.graph.conflictBehavior={0}".format(
+                    conflict_behavior
+                )
 
-            self.context.before_execute(_construct_request)
-            qry = ServiceOperationQuery(self, "move", None, payload, None, return_type)
-            self.context.add_query(qry)
+            qry = ServiceOperationQuery(self, "", None, payload, None, return_type)
+            self.context.add_query(qry).before_execute(_construct_request)
 
         if isinstance(parent, DriveItem):
 
             def _drive_item_loaded():
-                _create_and_add_query(ItemReference(_id=parent.id))
+                _move(ItemReference(_id=parent.id))
 
             parent.ensure_property("parentReference", _drive_item_loaded)
         else:
-            _create_and_add_query(parent)
+            _move(parent)
         return return_type
 
     def rename(self, new_name):
@@ -618,9 +623,9 @@ class DriveItem(BaseItem):
                 DriveRecipient, [DriveRecipient.from_email(r) for r in recipients]
             ),
             "message": message,
-            "expirationDateTime": expiration_datetime.isoformat() + "Z"
-            if expiration_datetime
-            else None,
+            "expirationDateTime": (
+                expiration_datetime.isoformat() + "Z" if expiration_datetime else None
+            ),
             "password": password,
             "retainInheritedPermissions": retain_inherited_permissions,
         }
@@ -662,7 +667,7 @@ class DriveItem(BaseItem):
         return self
 
     def restore(self, parent_reference=None, name=None):
-        # type: (ItemReference or None, str or None) -> DriveItem
+        # type: (Optional[ItemReference], str) -> "DriveItem"
         """
         Restore a driveItem that has been deleted and is currently in the recycle bin.
         NOTE: This functionality is currently only available for OneDrive Personal.
@@ -910,8 +915,6 @@ class DriveItem(BaseItem):
 
     def set_property(self, name, value, persist_changes=True):
         super(DriveItem, self).set_property(name, value, persist_changes)
-        if name == "parentReference":
-            pass
         return self
 
     def get_property(self, name, default_value=None):

office365/onedrive/listitems/list_item.py

@@ -38,6 +38,7 @@ class ListItem(BaseItem):
 
     @property
     def versions(self):
+        # type: () -> EntityCollection[ListItemVersion]
         """The list of previous versions of the list item."""
         return self.properties.get(
             "versions",

office365/onedrive/lists/collection.py

@@ -26,3 +26,9 @@ class ListCollection(EntityCollection[List]):
         qry = CreateEntityQuery(self, payload, return_type)
         self.context.add_query(qry)
         return return_type
+
+    def get_by_name(self, name):
+        return List(self.context, EntityPath(name, self.resource_path))
+
+    def get_by_id(self, list_id):
+        return List(self.context, EntityPath(list_id, self.resource_path))

office365/onedrive/sharepoint_ids.py

@@ -5,13 +5,30 @@ class SharePointIds(ClientValue):
     """The SharePointIds resource groups the various identifiers for an item stored in a SharePoint site or OneDrive
     for Business into a single structure."""
 
-    def __init__(self, list_id=None, list_item_id=None, list_item_unique_id=None):
+    def __init__(
+        self,
+        list_id=None,
+        list_item_id=None,
+        list_item_unique_id=None,
+        siteId=None,
+        siteUrl=None,
+        tenantId=None,
+        webId=None,
+    ):
         """
         :param str list_id: The unique identifier (guid) for the item's list in SharePoint.
         :param str list_item_id: An integer identifier for the item within the containing list.
         :param str list_item_unique_id: The unique identifier (guid) for the item within OneDrive for Business
             or a SharePoint site.
+        :param str siteId: The unique identifier (guid) for the item's site collection (SPSite).
+        :param str siteUrl: The SharePoint URL for the site that contains the item.
+        :param str tenantId: The unique identifier (guid) for the tenancy.
+        :param str webId: The unique identifier (guid) for the item's site (SPWeb).
         """
         self.listId = list_id
         self.listItemId = list_item_id
         self.listItemUniqueId = list_item_unique_id
+        self.siteId = siteId
+        self.siteUrl = siteUrl
+        self.tenantId = tenantId
+        self.webId = webId

office365/onedrive/shares/drive_item.py

@@ -8,7 +8,6 @@ from office365.onedrive.lists.list import List
 from office365.onedrive.permissions.permission import Permission
 from office365.onedrive.sites.site import Site
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.paths.v4.entity import EntityPath
 
 
 class SharedDriveItem(BaseItem):
@@ -48,7 +47,7 @@ class SharedDriveItem(BaseItem):
         """Used to access the underlying driveItem"""
         return self.properties.get(
             "driveItem",
-            DriveItem(self.context, EntityPath("driveItem", self.resource_path)),
+            DriveItem(self.context, ResourcePath("driveItem", self.resource_path)),
         )
 
     @property

office365/onedrive/storage/storage.py

@@ -0,0 +1,5 @@
+from office365.entity import Entity
+
+
+class Storage(Entity):
+    """Facilitates the structures of fileStorageContainers."""

office365/onedrive/workbooks/filter.py

@@ -2,11 +2,18 @@ from typing import Optional
 
 from office365.entity import Entity
 from office365.onedrive.workbooks.filter_criteria import WorkbookFilterCriteria
+from office365.runtime.queries.service_operation import ServiceOperationQuery
 
 
 class WorkbookFilter(Entity):
     """Manages the filtering of a table's column."""
 
+    def clear(self):
+        """Clear the filter on the given column."""
+        qry = ServiceOperationQuery(self, "clear")
+        self.context.add_query(qry)
+        return self
+
     @property
     def criteria(self):
         # type: () -> Optional[WorkbookFilterCriteria]

office365/onedrive/workbooks/filter_criteria.py

@@ -4,7 +4,14 @@ from office365.runtime.client_value import ClientValue
 class WorkbookFilterCriteria(ClientValue):
     """Represents the filtering criteria applied to a column."""
 
-    def __init__(self, operator=None, values=None):
-        """ """
+    def __init__(self, color=None, dynamicCriteria=None, operator=None, values=None):
+        """
+        :param str color:  The color applied to the cell.
+        :param str dynamicCriteria:  A dynamic formula specified in a custom filter.
+        :param str operator: An operator in a cell; for example, =, >, <, <=, or <>.
+        :param list values: The values that appear in the cell.
+        """
+        self.color = color
+        self.dynamicCriteria = dynamicCriteria
         self.operator = operator
         self.values = values

office365/onedrive/workbooks/tables/rows/collection.py

@@ -1,5 +1,7 @@
 from office365.entity_collection import EntityCollection
 from office365.onedrive.workbooks.tables.rows.row import WorkbookTableRow
+from office365.runtime.client_result import ClientResult
+from office365.runtime.queries.function import FunctionQuery
 
 
 class WorkbookTableRowCollection(EntityCollection[WorkbookTableRow]):
@@ -25,3 +27,21 @@ class WorkbookTableRowCollection(EntityCollection[WorkbookTableRow]):
              Any rows below the inserted row are shifted downwards. Zero-indexed.
         """
         return super(WorkbookTableRowCollection, self).add(values=values, index=index)
+
+    def count(self):
+        """"""
+        return_type = ClientResult(self.context, int())
+        qry = FunctionQuery(self, "count", None, return_type)
+        self.context.add_query(qry)
+        return return_type
+
+    def item_at(self, index):
+        # type: (int) -> WorkbookTableRow
+        """Gets a row based on its position in the collection.
+        :param int index: Index value of the object to be retrieved. Zero-indexed.
+        """
+        return_type = WorkbookTableRow(self.context)
+        self.add_child(return_type)
+        qry = FunctionQuery(self, "itemAt", [index], return_type)
+        self.context.add_query(qry)
+        return return_type

office365/onedrive/workbooks/tables/rows/row.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import List, Optional
 
 from office365.entity import Entity
 
@@ -14,6 +14,7 @@ class WorkbookTableRow(Entity):
 
     @property
     def values(self):
+        # type: () -> Optional[List]
         """
         Represents the raw values of the specified range. The data returned could be of type string, number,
         or a boolean. Cell that contain an error will return the error string.

office365/onedrive/workbooks/workbook.py

@@ -1,3 +1,5 @@
+from typing_extensions import Self
+
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.onedrive.workbooks.applications.application import WorkbookApplication
@@ -50,20 +52,21 @@ class Workbook(Entity):
         return return_type
 
     def refresh_session(self, session_id):
+        # type: (str) -> Self
         """Use this API to refresh an existing workbook session.
         :param str session_id: Identifier of the workbook session
         """
-        qry = ServiceOperationQuery(self, "refreshSession")
-        self.context.add_query(qry)
 
         def _construct_request(request):
             # type: (RequestOptions) -> None
             request.set_header("workbook-session-id", session_id)
 
-        self.context.before_execute(_construct_request)
+        qry = ServiceOperationQuery(self, "refreshSession")
+        self.context.add_query(qry).before_query_execute(_construct_request)
         return self
 
     def close_session(self, session_id):
+        # type: (str) -> Self
         """Use this API to close an existing workbook session.
         :param str session_id: Identifier of the workbook session
         """
@@ -73,8 +76,7 @@ class Workbook(Entity):
             # type: (RequestOptions) -> None
             request.set_header("workbook-session-id", session_id)
 
-        self.context.before_execute(_construct_request)
-        self.context.add_query(qry)
+        self.context.add_query(qry).before_query_execute(_construct_request)
         return self
 
     @property

office365/onenote/internal/multipart_page_query.py

@@ -3,6 +3,7 @@ from typing import AnyStr
 
 from office365.runtime.compat import get_mime_type, message_as_bytes_or_string
 from office365.runtime.http.http_method import HttpMethod
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.queries.batch import create_boundary
 from office365.runtime.queries.client_query import ClientQuery
 
@@ -32,9 +33,7 @@ class OneNotePageCreateQuery(ClientQuery):
         self._files = attachment_files
 
     def _construct_multipart_request(self, request):
-        """
-        :type request: office365.runtime.http.request_options.RequestOptions
-        """
+        # type: (RequestOptions) -> None
         request.method = HttpMethod.Post
         boundary = create_boundary("PageBoundary", True)
         request.set_header(

office365/outlook/category.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity import Entity
 
 
@@ -6,13 +8,18 @@ class OutlookCategory(Entity):
     The user defines categories in a master list, and can apply one or more
     of these user-defined categories to an item."""
 
+    def __str__(self):
+        return self.display_name or self.entity_type_name
+
     @property
     def color(self):
+        # type: () -> Optional[str]
         """A pre-set color constant that characterizes a category, and that is mapped to one of 25 predefined colors"""
         return self.properties.get("color", None)
 
     @property
     def display_name(self):
+        # type: () -> Optional[str]
         """A unique name that identifies a category in the user's mailbox.
         After a category is created, the name cannot be changed"""
         return self.properties.get("displayName", None)

office365/outlook/mail/item_body.py

@@ -6,7 +6,6 @@ class ItemBody(ClientValue):
 
     def __init__(self, content=None, content_type="Text"):
         """
-
         :param str content: The content of the item.
         :param str content_type: The type of the content. Possible values are text and html.
         """
@@ -14,5 +13,15 @@ class ItemBody(ClientValue):
         self.content = content
         self.contentType = content_type
 
+    @staticmethod
+    def text(content):
+        # type: (str) -> "ItemBody"
+        return ItemBody(content)
+
+    @staticmethod
+    def html(content):
+        # type: (str) -> "ItemBody"
+        return ItemBody(content, "html")
+
     def __repr__(self):
         return self.content

office365/outlook/mail/messages/collection.py

@@ -1,3 +1,5 @@
+from typing import List
+
 from office365.delta_collection import DeltaCollection
 from office365.outlook.mail.item_body import ItemBody
 from office365.outlook.mail.messages.message import Message
@@ -10,6 +12,7 @@ class MessageCollection(DeltaCollection[Message]):
         super(MessageCollection, self).__init__(context, Message, resource_path)
 
     def add(self, subject=None, body=None, to_recipients=None, **kwargs):
+        # type: (str, str|ItemBody, List[str], ...) -> Message
         """
         Create a draft of a new message in either JSON or MIME format.