#766 fix, SharePoint examples updates, typings enhancements

Author: vgrem

examples/onedrive/files/search.py

@@ -10,4 +10,6 @@
 client = GraphClient(acquire_token_by_username_password)
 result = client.search.query_drive_items("Guide.docx").execute_query()
 for item in result.value:
-    print("Search terms: {0}".format(item.searchTerms))
+    for hit_container in item.hitsContainers:
+        for hit in hit_container.hits:
+            print(hit.resource)

examples/onedrive/sites/__init__.py

@@ -10,5 +10,6 @@
     "Shared Documents/Financial Sample.xlsx"
 )
 folder_to = ctx.web.get_folder_by_server_relative_url("Shared Documents/archive")
+# folder_to = "Shared Documents/archive/2002/02"
 file_to = file_from.copyto(folder_to, True).execute_query()
-print("File has been copied into '{0}'".format(file_to))
+print("{0} copied into '{1}'".format(file_from, file_to))

examples/planner/__init__.py

@@ -11,5 +11,6 @@
 )
 
 folder_to = ctx.web.get_folder_by_server_relative_path("Shared Documents/archive")
+# folder_to = "Shared Documents/archive/2002/02"
 file_to = file_from.copyto_using_path(folder_to, True).execute_query()
-print("File has been copied into '{0}'".format(file_to.server_relative_path))
+print("{0} copied into {1}".format(file_from, file_to))

examples/sharepoint/files/copy_file.py

@@ -3,27 +3,18 @@
 """
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.files.move_operations import MoveOperations
-from tests import create_unique_name, test_team_site_url, test_user_credentials
+from tests import test_team_site_url, test_user_credentials
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
 
-print("Creating temporary folders and uploading a file...")
-path = "../../data/report #123.csv"
-folder_from = ctx.web.default_document_library().root_folder.add(
-    create_unique_name("from")
-)
-folder_to = ctx.web.default_document_library().root_folder.add(create_unique_name("to"))
-file = folder_from.files.upload(path).execute_query()
 
-# copies the file with a new name into folder
-print("Moving file to parent folder...")
-file_to = file.move_to_using_path(folder_to, MoveOperations.overwrite).execute_query()
-print(
-    "File has been copied from '{0}' into '{1}'".format(
-        file.server_relative_path, folder_to.serverRelativeUrl
-    )
+file_from = ctx.web.get_file_by_server_relative_path(
+    "Shared Documents/Financial Sample.xlsx"
 )
+# folder_to = ctx.web.get_folder_by_server_relative_url("Shared Documents")
+folder_to = "Shared Documents"
 
-print("Cleaning up...")
-folder_from.delete_object().execute_query()
-folder_to.delete_object().execute_query()
+file_to = file_from.move_to_using_path(
+    folder_to, MoveOperations.overwrite
+).execute_query()
+print("'{0}' moved into '{1}'".format(file_from, file_to))

examples/sharepoint/files/copy_using_path.py

@@ -4,8 +4,8 @@
 from office365.sharepoint.client_context import ClientContext
 from tests import test_team_site_url, test_user_credentials
 
-from_url = "Home_Archive.aspx"
-to_url = "Home.aspx"
+file_url = "Site Pages/Home.aspx"
+new_name = "NewHome.aspx"
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
-file = ctx.web.lists.get_by_title("Site Pages").root_folder.files.get_by_url(from_url)
-file.rename(to_url).execute_query()
+file = ctx.web.get_file_by_server_relative_path(file_url)
+file.rename(new_name).execute_query()

examples/sharepoint/files/move_file.py

@@ -14,4 +14,3 @@
     .execute_query()
 )
 print("Folder : {0} has been created".format(folder.serverRelativeUrl))
-folder.delete_object().execute_query()

examples/sharepoint/files/rename_page.py

@@ -3,9 +3,6 @@
 from tests import test_client_credentials, test_team_site_url
 
 client = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
-target_folder = client.web.default_document_library().root_folder.folders.get_by_url(
-    "2017"
-)
-
-doc_set = DocumentSet.create(client, target_folder, "07").execute_query()
+lib = client.web.default_document_library()
+doc_set = DocumentSet.create(client, lib.root_folder, "07").execute_query()
 print("DocSet created: {0}".format(doc_set.name))

examples/sharepoint/folders/create.py

@@ -5,7 +5,7 @@
 from tests import test_client_credentials, test_team_site_url
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
-folder_path = "SitePages"
+folder_path = "Shared Documents"
 folder = (
     ctx.web.get_folder_by_server_relative_url(folder_path)
     .select(["Exists"])

examples/sharepoint/folders/create_doc_set.py

@@ -1,7 +1,9 @@
+"""
+Get folder at the specified path
+"""
 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)
-folder = ctx.web.folders.get_by_path("Shared Documents")
-ctx.load(folder, ["ServerRelativeUrl", "Folders"]).execute_query()
-print(folder.serverRelativeUrl)
+folder = ctx.web.folders.get_by_path("Shared Documents").get().execute_query()
+print(folder)

examples/sharepoint/folders/folder_exists.py

@@ -1,5 +1,5 @@
 """
-Gets Folder properties
+Gets folder properties
 """
 from office365.sharepoint.client_context import ClientContext
 from tests import test_client_credentials, test_team_site_url

examples/sharepoint/folders/get_by_path.py

@@ -8,7 +8,7 @@
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
 folders = (
-    ctx.web.default_document_library().root_folder.get_folders(True).execute_query()
+    ctx.web.default_document_library().root_folder.get_folders(False).execute_query()
 )
 for folder in folders:
     print(

examples/sharepoint/folders/get_props.py

@@ -1,14 +1,14 @@
+"""
+Demonstrates how to update folder properties
+"""
 from office365.sharepoint.client_context import ClientContext
 from tests import test_team_site_url, test_user_credentials
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
 
-target_folder_url = "/Shared Documents/Archive/2022/09/01"
-target_folder = (
-    ctx.web.default_document_library().root_folder.folders.ensure_folder_path(
-        "Archive/2022/09"
-    )
-)
-folder_item = target_folder.list_item_all_fields
-folder_item.set_property("DocScope", "Public").update().execute_query()
-print(target_folder.serverRelativeUrl)
+folder_url = "Shared Documents/Archive"
+folder = ctx.web.get_folder_by_server_relative_path(folder_url)
+folder_item = folder.list_item_all_fields
+prop_name = "DocScope"
+prop_value = "Public"
+folder_item.set_property(prop_name, prop_value).update().execute_query()

examples/sharepoint/folders/list_folders.py

@@ -0,0 +1,16 @@
+"""
+This common way of retrieving List Items from a List, only the default properties are getting returned
+
+Official documentation:
+https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/working-with-lists-and-list-items-with-rest#working-with-list-items-by-using-rest
+"""
+
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_credentials, test_team_site_url
+
+list_title = "Company Tasks"
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+tasks_list = ctx.web.lists.get_by_title(list_title)
+items = tasks_list.items.get().execute_query()
+for item in items:
+    print("{0}".format(item.properties.get("Title")))

examples/sharepoint/folders/set_properties.py

@@ -1,3 +1,7 @@
+"""
+Share a Web with user
+"""
+
 import sys
 
 from office365.sharepoint.client_context import ClientContext

examples/sharepoint/listitems/read.py

@@ -6,7 +6,6 @@
 import sys
 
 from office365.graph_client import GraphClient
-from office365.teams.team import Team
 from tests import test_user_principal_name
 from tests.graph_case import acquire_token_by_client_credentials
 
@@ -15,7 +14,7 @@
 if len(teams) < 1:
     sys.exit("No teams found")
 
-team = teams[0]  # type: Team
+team = teams[0]
 result = team.primary_channel.does_user_have_access(
     user_principal_name=test_user_principal_name
 ).execute_query()

examples/sharepoint/listitems/read_props.py

@@ -5,7 +5,6 @@
 """
 
 from office365.graph_client import GraphClient
-from office365.teams.team import Team
 from tests.graph_case import acquire_token_by_client_credentials
 
 client = GraphClient(acquire_token_by_client_credentials)

examples/sharepoint/sharing/share_web.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from typing import AnyStr, Optional
 
 from office365.communications.onlinemeetings.participants import MeetingParticipants
 from office365.entity import Entity
@@ -14,49 +15,37 @@ class OnlineMeeting(Entity):
 
     @property
     def allow_attendee_to_enable_camera(self):
-        """
-        Indicates whether attendees can turn on their camera.
-        :rtype: str
-        """
+        # type: () -> Optional[bool]
+        """Indicates whether attendees can turn on their camera."""
         return self.properties.get("allowAttendeeToEnableCamera", None)
 
     @property
     def allow_attendee_to_enable_mic(self):
-        """
-        Indicates whether attendees can turn on their microphone.
-        :rtype: str
-        """
+        # type: () -> Optional[bool]
+        """Indicates whether attendees can turn on their microphone."""
         return self.properties.get("allowAttendeeToEnableMic", None)
 
     @property
     def allowed_presenters(self):
-        """
-        Specifies who can be a presenter in a meeting. Possible values are listed in the following table.
-        """
+        """Specifies who can be a presenter in a meeting. Possible values are listed in the following table."""
         return self.properties.get("allowedPresenters", StringCollection())
 
     @property
     def allow_meeting_chat(self):
-        """
-        Specifies the mode of meeting chat.
-        :rtype: str or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies the mode of meeting chat."""
         return self.properties.get("allowMeetingChat", None)
 
     @property
     def allow_participants_to_change_name(self):
-        """
-        Specifies if participants are allowed to rename themselves in an instance of the meeting.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies if participants are allowed to rename themselves in an instance of the meeting."""
         return self.properties.get("allowParticipantsToChangeName", None)
 
     @property
     def attendee_report(self):
-        """
-        The content stream of the attendee report of a Microsoft Teams live event.
-        :rtype: bytes or None
-        """
+        # type: () -> Optional[AnyStr]
+        """The content stream of the attendee report of a Microsoft Teams live event."""
         return self.properties.get("attendeeReport", None)
 
     @property
@@ -68,17 +57,13 @@ def participants(self):
 
     @property
     def subject(self):
-        """
-        The subject of the online meeting.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The subject of the online meeting."""
         return self.properties.get("subject", None)
 
     @subject.setter
     def subject(self, value):
-        """
-        :type value: str
-        """
+        # type: (str) -> None
         self.set_property("subject", value)
 
     @property
@@ -88,9 +73,9 @@ def start_datetime(self):
 
     @start_datetime.setter
     def start_datetime(self, value):
+        # type: (datetime) -> None
         """
         Sets the meeting start time in UTC.
-        :type value: datetime.datetime
         """
         self.set_property("startDateTime", value.isoformat())
 
@@ -101,10 +86,8 @@ def end_datetime(self):
 
     @end_datetime.setter
     def end_datetime(self, value):
-        """
-        Sets the meeting end time in UTC.
-        :type value: datetime.datetime
-        """
+        # type: (datetime) -> None
+        """Sets the meeting end time in UTC."""
         self.set_property("endDateTime", value.isoformat())
 
     @property
@@ -114,11 +97,13 @@ def join_information(self):
 
     @property
     def join_web_url(self):
+        # type: () -> Optional[str]
         """The join URL of the online meeting. Read-only."""
         return self.properties.get("joinWebUrl", None)
 
     @property
     def video_teleconference_id(self):
+        # type: () -> Optional[str]
         """The video teleconferencing ID."""
         return self.properties.get("videoTeleconferenceId", None)
 

examples/teams/__init__.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from typing import Optional
 
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
@@ -15,39 +16,39 @@ class UserActivity(Entity):
 
     @property
     def activation_url(self):
+        # type: () -> Optional[str]
         """URL used to launch the activity in the best native experience represented by the appId.
         Might launch a web-based app if no native app exists
-        :rtype: str or None
         """
         return self.properties.get("activationUrl", None)
 
     @property
     def activity_source_host(self):
+        # type: () -> Optional[str]
         """Required. URL for the domain representing the cross-platform identity mapping for the app.
         Mapping is stored either as a JSON file hosted on the domain or configurable via Windows Dev Center.
         The JSON file is named cross-platform-app-identifiers and is hosted at root of your HTTPS domain,
         either at the top level domain or include a sub domain.
         For example: https://contoso.com or https://myapp.contoso.com but NOT https://myapp.contoso.com/somepath.
         You must have a unique file and domain (or sub domain) per cross-platform app identity.
         For example, a separate file and domain is needed for Word vs. PowerPoint.
-        :rtype: str or None
         """
         return self.properties.get("activitySourceHost", None)
 
     @property
     def app_activity_id(self):
+        # type: () -> Optional[str]
         """
         The unique activity ID in the context of the app - supplied by caller and immutable thereafter.
-        :rtype: str
         """
         return self.properties.get("appActivityId", None)
 
     @property
     def app_display_name(self):
+        # type: () -> Optional[str]
         """
         Short text description of the app used to generate the activity for use in cases when the app is
         not installed on the user’s local device.
-        :rtype: str
         """
         return self.properties.get("appDisplayName", None)