typings improvements for Outlook & SharePoint API, new methods for Ma…

…ilFolder type, examples updates

examples/auth/interactive.py

@@ -15,4 +15,4 @@
 
 client = GraphClient.with_token_interactive(test_tenant, test_client_id)
 me = client.me.get().execute_query()
-print(me.user_principal_name)
+print("Welcome,  {0}!".format(me.given_name))

examples/outlook/calendars/get_schedule.py

@@ -7,7 +7,6 @@
 The following example gets the availability information for user for the specified date, time, and time zone.
 """
 
-import json
 from datetime import datetime, timedelta
 
 from office365.graph_client import GraphClient
@@ -20,4 +19,5 @@
 result = client.me.calendar.get_schedule(
     [test_user_principal_name], start_time, end_time
 ).execute_query()
-print(json.dumps(result.value.to_json(), indent=4))
+for item in result.value:
+    print(item.availabilityView)

examples/outlook/messages/create_subscription.py

@@ -1,7 +1,7 @@
 """
-Demonstrates how to  send a change notification when the user receives a new mail.
+Demonstrates how to send a change notification when the user receives a new mail.
 
-https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0&tabs=http
+https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0
 """
 import datetime
 

examples/outlook/messages/download.py

@@ -9,13 +9,12 @@
 import tempfile
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 messages = client.me.messages.select(["id", "subject"]).top(2).get().execute_query()
 with tempfile.TemporaryDirectory() as local_path:
-    for message in messages:  # type: Message
+    for message in messages:
         with open(os.path.join(local_path, message.id + ".eml"), "wb") as local_file:
             message.download(
                 local_file

examples/outlook/messages/download_with_attachments.py

@@ -1,15 +1,13 @@
 """
 Demonstrates how to download message attachments
 
-https://learn.microsoft.com/en-us/graph/api/attachment-get?view=graph-rest-1.0&tabs=http
+https://learn.microsoft.com/en-us/graph/api/attachment-get?view=graph-rest-1.0
 """
 
 import os
 import tempfile
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.attachments.attachment import Attachment
-from office365.outlook.mail.messages.message import Message
 from tests import test_user_principal_name
 from tests.graph_case import acquire_token_by_client_credentials
 
@@ -18,13 +16,13 @@
 messages = (
     user.messages.filter("hasAttachments eq true")
     .expand(["attachments"])
-    .top(1)
+    .top(10)
     .get()
     .execute_query()
 )
 with tempfile.TemporaryDirectory() as local_path:
-    for message in messages:  # type: Message
-        for attachment in message.attachments:  # type: Attachment
+    for message in messages:
+        for attachment in message.attachments:
             with open(os.path.join(local_path, attachment.name), "wb") as local_file:
                 attachment.download(local_file).execute_query()
             print("Message attachment downloaded into {0}".format(local_file.name))

examples/outlook/messages/empty_folder.py

@@ -0,0 +1,12 @@
+"""
+Empties the mail folder
+
+"""
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
+client.me.mail_folders["Inbox"].empty().execute_query()
+print("Inbox has been emptied")

examples/outlook/messages/get_basic_props.py

@@ -4,12 +4,11 @@
 """
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests import test_user_principal_name
 from tests.graph_case import acquire_token_by_client_credentials
 
 client = GraphClient(acquire_token_by_client_credentials)
 user = client.users[test_user_principal_name]
 messages = user.messages.select(["id", "subject"]).top(10).get().execute_query()
-for message in messages:  # type: Message
+for message in messages:
     print(message.subject)

examples/outlook/messages/get_with_body.py

@@ -3,14 +3,13 @@
 
 Requires Mail.Read permission at least
 
-https://learn.microsoft.com/en-us/graph/api/message-get?view=graph-rest-1.0&tabs=http
+https://learn.microsoft.com/en-us/graph/api/message-get?view=graph-rest-1.0
 """
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
-messages = client.me.messages.select(["subject", "body"]).top(1).get().execute_query()
-for message in messages:  # type: Message
-    print(message.body.content)
+messages = client.me.messages.select(["subject", "body"]).top(10).get().execute_query()
+for message in messages:
+    print(message.subject)

examples/outlook/messages/list_all.py

@@ -8,6 +8,6 @@
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
-messages = client.me.messages.get().execute_query()
+messages = client.me.messages.get().top(10).execute_query()
 for m in messages:
     print(m.subject)

examples/outlook/messages/list_attachments.py

@@ -0,0 +1,23 @@
+"""
+List attachments
+
+https://learn.microsoft.com/en-us/graph/api/message-list-attachments?view=graph-rest-1.0
+"""
+
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
+messages = (
+    client.me.messages.filter("hasAttachments eq true")
+    .expand(["attachments"])
+    .top(10)
+    .get()
+    .execute_query()
+)
+
+for message in messages:
+    for attachment in message.attachments:
+        print("Message: {0}, Attachment: {1}".format(message.subject, attachment.name))

examples/outlook/messages/list_new.py

@@ -5,7 +5,6 @@
 """
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)

examples/outlook/messages/mark_all_as_read.py

@@ -0,0 +1,11 @@
+"""
+
+"""
+from office365.graph_client import GraphClient
+from tests import test_client_id, test_password, test_tenant, test_username
+
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
+client.me.mail_folders["Inbox"].mark_all_items_as_unread().execute_query()
+print("All messages marked as read")

examples/outlook/messages/mark_as_read.py

@@ -1,18 +1,18 @@
 """
 Mark message as read example
 
-https://learn.microsoft.com/en-us/graph/api/message-update?view=graph-rest-1.0&tabs=http
+https://learn.microsoft.com/en-us/graph/api/message-update?view=graph-rest-1.0
 """
 
 import sys
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 messages = client.me.messages.top(1).get().execute_query()
 if len(messages) == 0:
-    sys.exit("No messages found")
-first_message = messages[0]  # type: Message
+    sys.exit("No messages were found")
+first_message = messages[0]
 first_message.set_property("isRead", True).update().execute_query()
+print("Message {0} has been marked as read".format(first_message.subject))

examples/outlook/messages/reply.py

@@ -7,13 +7,12 @@
 import sys
 
 from office365.graph_client import GraphClient
-from office365.outlook.mail.messages.message import Message
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 messages = client.me.messages.top(1).get().execute_query()
 if len(messages) == 0:
     sys.exit("No messages were found")
 
-first_message = messages[0]  # type: Message
+first_message = messages[0]
 first_message.reply(comment="Fanny, would you join us next time?").execute_query()

examples/outlook/messages/send.py

@@ -5,12 +5,12 @@
 """
 
 from office365.graph_client import GraphClient
-from tests import test_user_principal_name
+from tests import test_user_principal_name_alt
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 client.me.send_mail(
     subject="Meet for lunch?",
     body="The new cafeteria is open.",
-    to_recipients=["[email protected]", test_user_principal_name],
+    to_recipients=["[email protected]", test_user_principal_name_alt],
 ).execute_query()

examples/outlook/messages/send_with_attachment.py

@@ -1,17 +1,19 @@
 """
 Create a message with a file attachment and send the message
 
-https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0&tabs=http
+https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0
 """
 
 from office365.graph_client import GraphClient
+from tests import test_user_principal_name_alt
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 client.me.send_mail(
     subject="Meet for lunch?",
     body="The new cafeteria is open.",
-    to_recipients=["[email protected]"],
+    to_recipients=["[email protected]", test_user_principal_name_alt],
 ).add_file_attachment(
     "attachment.txt", "--Some content goes here--", "text/plain"
 ).execute_query()
+print("Message has been sent")

examples/sharepoint/apps/list_apps.py

@@ -1,10 +1,9 @@
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.marketplace.app_metadata import CorporateCatalogAppMetadata
 from tests import test_admin_credentials, test_admin_site_url
 
 admin_client = ClientContext(test_admin_site_url).with_credentials(
     test_admin_credentials
 )
 apps = admin_client.web.tenant_app_catalog.available_apps.get().execute_query()
-for app in apps:  # type: CorporateCatalogAppMetadata
+for app in apps:
     print(app.title)

examples/sharepoint/listitems/versions/list.py

@@ -0,0 +1,18 @@
+"""
+Demonstrates how to retain the history for list items.
+"""
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_credentials, test_team_site_url
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+items = (
+    ctx.web.lists.get_by_title("Site Pages")
+    .items.get()
+    .expand(["Versions"])
+    .top(10)
+    .execute_query()
+)
+
+for item in items:
+    for version in item.versions:
+        print(version)

examples/sharepoint/search/search_sites.py

@@ -1,3 +1,8 @@
+"""
+Search SharePoint sites the current user is member of
+
+"""
+
 from office365.sharepoint.client_context import ClientContext
 from tests import test_site_url, test_user_credentials
 

examples/sharepoint/users/export_site_users.py

@@ -1,5 +1,7 @@
 """
 Retrieves site users
+
+
 """
 
 from office365.sharepoint.client_context import ClientContext

examples/sharepoint/users/get_onedrive_quota_max.py

@@ -0,0 +1,9 @@
+"""
+Get OneDrive quota max for a user
+"""
+from office365.sharepoint.client_context import ClientContext
+from tests import test_password, test_site_url, test_username
+
+ctx = ClientContext(test_site_url).with_user_credentials(test_username, test_password)
+result = ctx.people_manager.get_user_onedrive_quota_max(test_username).execute_query()
+print(result.value)

office365/graph_client.py

@@ -1,4 +1,4 @@
-from typing import Callable, List, Optional
+from typing import Any, Callable, List, Optional
 
 from office365.booking.solutions.root import SolutionsRoot
 from office365.communications.cloud_communications import CloudCommunications
@@ -120,6 +120,7 @@ def _acquire_token():
     def with_client_secret(
         tenant, client_id, client_secret, scopes=None, token_cache=None
     ):
+        # type: (str, str, str, List[str], Any) -> "GraphClient"
         """
         Initializes the confidential client with client secret
 

office365/onedrive/columns/definition.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.base_item import BaseItem
 from office365.onedrive.columns.boolean import BooleanColumn
 from office365.onedrive.columns.calculated import CalculatedColumn
@@ -32,23 +34,21 @@ class ColumnDefinition(BaseItem):
 
     @property
     def display_name(self):
-        """The user-facing name of the column.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The user-facing name of the column."""
         return self.properties.get("displayName", None)
 
     @property
     def enforce_unique_values(self):
+        # type: () -> Optional[bool]
         """
         If true, no two list items may have the same value for this column.
-
-        :rtype: bool or None
         """
         return self.properties.get("enforceUniqueValues", None)
 
     @property
     def indexed(self):
+        # type: () -> Optional[bool]
         """Specifies whether the column values can used for sorting and searching."""
         return self.properties.get("indexed", None)
 
@@ -61,6 +61,7 @@ def content_approval_status(self):
 
     @property
     def column_group(self):
+        # type: () -> Optional[str]
         """For site columns, the name of the group this column belongs to. Helps organize related columns."""
         return self.properties.get("columnGroup", None)
 
@@ -131,16 +132,14 @@ def hyperlink_or_picture(self):
 
     @property
     def hidden(self):
-        """Specifies whether the column is displayed in the user interface.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether the column is displayed in the user interface."""
         return self.properties.get("hidden", None)
 
     @property
     def is_deletable(self):
-        """Indicates whether this column can be deleted.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Indicates whether this column can be deleted."""
         return self.properties.get("isDeletable", None)
 
     @property