SharePoint API: folders namespace enhancements

Author: vgrem

examples/outlook/messages/download.py

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

examples/sharepoint/folders/copy_folder.py

@@ -7,13 +7,12 @@
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
 
 # creates a temporary folder first in a Documents library
-folder_name = create_unique_name("New folder")
-folder_from = ctx.web.default_document_library().root_folder.add(folder_name)
+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"))
 
 # copies the folder with a new name
-new_folder_name = create_unique_name("Copied folder")
-folder_to = folder_from.copy_to(new_folder_name).execute_query()
-print("Folder has been copied from '{0}' into '{1}'".format(folder_from.serverRelativeUrl, folder_to.serverRelativeUrl))
+folder = folder_from.copy_to_using_path(folder_to).execute_query()
+print("Folder has been copied from '{0}' into '{1}'".format(folder_from.serverRelativeUrl, folder.serverRelativeUrl))
 
 # clean up
 folder_from.delete_object().execute_query()

examples/sharepoint/folders/move.py

@@ -6,17 +6,16 @@
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
 
-folder_name = create_unique_name("New folder")
-print("Creating a temporary folder in a Documents library ...")
-folder_from = ctx.web.default_document_library().root_folder.add(folder_name).execute_query()
-print("Folder '{0}' has been created".format(folder_from.serverRelativeUrl))
 
-new_folder_name = create_unique_name("Moved folder")
+print("Creating a temporary folders in a Documents library ...")
+folder_from = ctx.web.default_document_library().root_folder.add(create_unique_name("in"))
+folder_to_parent = ctx.web.default_document_library().root_folder.add(create_unique_name("out"))
+# folder_to_url = "Shared Documents/archive"
+
 print("Moving folder...")
-folder_to = folder_from.move_to(new_folder_name).execute_query()
-print("Folder has been moved from '{0}' into '{1}'".format(folder_from.serverRelativeUrl, folder_to.serverRelativeUrl))
+folder_to = folder_from.move_to_using_path(folder_to_parent).execute_query()
+print("Folder has been moved into '{0}'".format(folder_to.serverRelativeUrl))
 
 print("Cleaning up temporary folders ...")
-folder_from.delete_object().execute_query()
-folder_to.delete_object().execute_query()
+folder_to_parent.delete_object().execute_query()
 print("Done")

office365/outlook/mail/messages/message.py

@@ -39,16 +39,12 @@ def download(self, file_object):
 
         :type file_object: typing.IO
         """
-        result = self.get_content()
-
-        def _content_downloaded(resp):
+        def _save_content(return_type):
             """
-            :type resp: requests.Response
+            :type return_type: ClientResult
             """
-            resp.raise_for_status()
-            file_object.write(result.value)
-
-        self.context.after_execute(_content_downloaded)
+            file_object.write(return_type.value)
+        self.get_content().after_execute(_save_content)
         return self
 
     def get_content(self):

office365/runtime/queries/update_entity.py

@@ -2,10 +2,10 @@
 
 
 class UpdateEntityQuery(ClientQuery):
-    def __init__(self, entity_to_update):
+    def __init__(self, update_type):
         """
         Update client object query
 
-        :type entity_to_update: office365.runtime.client_object.ClientObject
+        :type update_type: office365.runtime.client_object.ClientObject
         """
-        super(UpdateEntityQuery, self).__init__(entity_to_update.context, entity_to_update, entity_to_update)
+        super(UpdateEntityQuery, self).__init__(update_type.context, update_type, update_type)

office365/sharepoint/files/file.py

@@ -366,15 +366,16 @@ def publish(self, comment):
         return self
 
     def unpublish(self, comment):
-        """Removes the file from content approval or unpublish a major version.
+        """Removes the file from content approval or unpublishes a major version.
 
-        :type comment: str
+        :param str comment: Specifies the comment for UnPublish. Its length MUST be equal to or less than 1023.
         """
         qry = ServiceOperationQuery(self, "unpublish", {"comment": comment})
         self.context.add_query(qry)
         return self
 
     def check_access_and_post_view_audit_event(self):
+        """"""
         return_type = ClientResult(self.context, bool())
         qry = ServiceOperationQuery(self, "CheckAccessAndPostViewAuditEvent", return_type=return_type)
         self.context.add_query(qry)
@@ -396,13 +397,11 @@ def checkin(self, comment, checkin_type):
             https://docs.microsoft.com/en-us/previous-versions/office/sharepoint-csom/ee542953(v%3Doffice.15)
         :param int checkin_type: Specifies the type of check-in.
         """
-        qry = ServiceOperationQuery(self,
-                                    "checkin",
-                                    {
-                                        "comment": comment,
-                                        "checkInType": checkin_type
-                                    }
-                                    )
+        params = {
+           "comment": comment,
+           "checkInType": checkin_type
+        }
+        qry = ServiceOperationQuery(self, "checkin", params)
         self.context.add_query(qry)
         return self
 

office365/sharepoint/folders/folder.py

@@ -56,57 +56,82 @@ def get_sharing_information(self):
         """Gets the sharing information for a folder."""
         return self.list_item_all_fields.get_sharing_information()
 
-    def move_to(self, new_url, parent_folder=None):
+    def move_to(self, destination):
         """
-        Moves the folder and its contents to a new folder at the specified URL.
+        Moves the folder and its contents under a new folder at the specified destination.
         This method applies only to the context of a single site.
 
         An exception is thrown if a folder with the same name as specified in the parameter already exists.
 
-        :param str new_url: A string that specifies the URL for the new folder.
-        :param Folder or None parent_folder: The existing parent folder where to move folder
+        :param str or Folder destination: Specifies the server relative url or an existing folder
+            where to move a folder.
         """
-        if parent_folder is None:
-            parent_folder = self.parent_folder
 
-        return_type = Folder(self.context)
+        def _update_folder(url):
+            self.set_property("ServerRelativeUrl", url)
 
-        def _parent_folder_resolved():
-            new_path = SPResPath.create_relative(parent_folder.serverRelativeUrl, new_url)
-            return_type.set_property("ServerRelativeUrl", str(new_path))
-            qry = ServiceOperationQuery(self, "MoveTo", {"newUrl": str(new_path)})
-            self.context.add_query(qry)
+        def _move_to(destination_folder):
+            """
+            :type destination_folder: Folder
+            """
+            destination_url = "/".join([destination_folder.serverRelativeUrl, self.name])
+            qry = ServiceOperationQuery(self, "MoveTo", {"newUrl": destination_url})
+            self.context.add_query(qry).after_query_execute(_update_folder, destination_url)
 
-        parent_folder.ensure_property("ServerRelativeUrl", _parent_folder_resolved)
-        return return_type
+        def _source_folder_resolved():
+            if isinstance(destination, Folder):
+                destination.ensure_property("ServerRelativeUrl", _move_to, destination)
+            else:
+                self.context.web.ensure_folder_path(destination).after_execute(_move_to)
+
+        self.ensure_properties(["ServerRelativeUrl", "Name"], _source_folder_resolved)
+        return self
+
+    def move_to_using_path(self, destination):
+        """
+        Moves the folder and its contents to a new folder at the specified path.
+        An exception is thrown if a folder with the same name as specified in the parameter already exists.
+
+        :param str or Folder destination: Specifies the server relative url or an existing folder
+            where to move a folder.
+        """
+
+        def _update_folder(url):
+            self.set_property("ServerRelativePath", url)
+
+        def _move_to_using_path(destination_folder):
+            """
+            :type destination_folder: Folder
+            """
+            destination_url = "/".join([str(destination_folder.server_relative_path), self.name])
+            qry = ServiceOperationQuery(self, "MoveToUsingPath", {"DecodedUrl": destination_url})
+            self.context.add_query(qry).after_query_execute(_update_folder, destination_url)
 
-    def move_to_with_parameters(self, new_relative_url, retain_editor_and_modified=False):
-        """Moves the folder with files to the destination URL.
+        def _source_folder_resolved():
+            if isinstance(destination, Folder):
+                destination.ensure_property("ServerRelativePath", _move_to_using_path, destination)
+            else:
+                self.context.web.ensure_folder_path(destination).after_execute(_move_to_using_path)
+
+        self.ensure_properties(["ServerRelativePath", "Name"], _source_folder_resolved)
+        return self
+
+    def move_to_using_path_with_parameters(self, new_relative_path, retain_editor_and_modified=False):
+        """Moves the folder with files to the destination Path.
 
-        :type new_relative_url: str
-        :type retain_editor_and_modified: bool
+        :param str new_relative_path: A full URL path that represents the destination folder.
+        :param bool retain_editor_and_modified:
         """
         return_type = Folder(self.context)
-        return_type.set_property("ServerRelativeUrl", new_relative_url)
+        return_type.set_property("ServerRelativePath", SPResPath(new_relative_path))
 
         def _move_folder():
             opt = MoveCopyOptions(retain_editor_and_modified_on_move=retain_editor_and_modified)
-            MoveCopyUtil.move_folder(self.context, self.serverRelativeUrl, new_relative_url, opt)
+            MoveCopyUtil.move_folder_by_path(self.context, self.server_relative_path.DecodedUrl, new_relative_path, opt)
 
-        self.ensure_property("ServerRelativeUrl", _move_folder)
+        self.ensure_property("ServerRelativePath", _move_folder)
         return return_type
 
-    def move_to_using_path(self, new_path):
-        """
-        Moves the folder and its contents to a new folder at the specified path.
-        An exception is thrown if a folder with the same name as specified in the parameter already exists.
-
-        :param str new_path: Specifies the destination path.
-        """
-        qry = ServiceOperationQuery(self, "MoveToUsingPath", SPResPath(new_path))
-        self.context.add_query(qry)
-        return self
-
     def share_link(self, link_kind, expiration=None):
         """Creates a tokenized sharing link for a folder based on the specified parameters and optionally
         sends an email to the people that are listed in the specified parameters.
@@ -252,66 +277,65 @@ def _loaded():
                                                                 include_anonymous_links_in_notification,
                                                                 propagate_acl,
                                                                 return_type)
+
         self.ensure_property("ServerRelativePath", _loaded)
         return return_type
 
-    def copy_to(self, new_relative_url, keep_both=False, reset_author_and_created=False, parent_folder=None):
+    def copy_to(self, destination, keep_both=False, reset_author_and_created=False):
         """Copies the folder with files to the destination URL.
 
-        :param str new_relative_url: Folder name or server relative url
+        :param str or Folder destination: Parent folder object or server relative folder url
         :param bool keep_both: bool
         :param bool reset_author_and_created:
-        :param Folder or None parent_folder: The existing parent folder
         """
-        if parent_folder is None:
-            parent_folder = self.parent_folder
         return_type = Folder(self.context)
+        self.parent_collection.add_child(return_type)
 
-        def _parent_folder_resolved():
-            new_path = SPResPath.create_relative(parent_folder.serverRelativeUrl, new_relative_url)
-            return_type.set_property("ServerRelativeUrl", str(new_path))
-            self.ensure_property("ServerRelativeUrl", _copy_to, folder_path=new_path)
-        parent_folder.ensure_property("ServerRelativeUrl", _parent_folder_resolved)
-
-        def _copy_to(folder_path):
+        def _copy_folder(destination_folder):
+            """
+            :type destination_folder: Folder
+            """
+            destination_url = "/".join([destination_folder.serverRelativeUrl, self.name])
+            return_type.set_property("ServerRelativeUrl", destination_url)
             opts = MoveCopyOptions(keep_both=keep_both, reset_author_and_created_on_copy=reset_author_and_created)
-            MoveCopyUtil.copy_folder(self.context, self.serverRelativeUrl, str(folder_path), opts)
+            MoveCopyUtil.copy_folder(self.context, self.serverRelativeUrl, destination_url, opts)
+
+        def _source_folder_resolved():
+            if isinstance(destination, Folder):
+                destination.ensure_property("ServerRelativeUrl", _copy_folder, destination)
+            else:
+                self.context.web.ensure_folder_path(destination).after_execute(_copy_folder)
 
+        self.ensure_property("ServerRelativeUrl", _source_folder_resolved)
         return return_type
 
-    def copy_to_using_path(self, new_relative_path, keep_both=False, reset_author_and_created=False):
+    def copy_to_using_path(self, destination, keep_both=False, reset_author_and_created=False):
         """Copies the folder with files to the destination Path.
 
-        :type new_relative_path: str
+        :param str or Folder destination: Parent folder object or server relative folder url
         :type keep_both: bool
         :type reset_author_and_created: bool
         """
 
         return_type = Folder(self.context)
-        return_type.set_property("ServerRelativePath", new_relative_path)
+        self.parent_collection.add_child(return_type)
 
-        def _copy_folder():
+        def _copy_folder_by_path(destination_folder):
+            """
+            :type destination_folder: Folder
+            """
+            destination_url = "/".join([str(destination_folder.server_relative_path), self.name])
+            return_type.set_property("ServerRelativePath", destination_url)
             opts = MoveCopyOptions(keep_both=keep_both, reset_author_and_created_on_copy=reset_author_and_created)
-            MoveCopyUtil.copy_folder_by_path(self.context, str(self.server_relative_path), new_relative_path,
-                                             opts)
-
-        self.ensure_property("ServerRelativePath", _copy_folder)
-        return return_type
-
-    def move_to_using_path_with_parameters(self, new_relative_path, retain_editor_and_modified=False):
-        """Moves the folder with files to the destination Path.
-
-        :param str new_relative_path: A full URL path that represents the destination folder.
-        :param bool retain_editor_and_modified:
-        """
-        return_type = Folder(self.context)
-        return_type.set_property("ServerRelativePath", SPResPath(new_relative_path))
+            MoveCopyUtil.copy_folder_by_path(self.context, str(self.server_relative_path), destination_url, opts)
 
-        def _move_folder():
-            opt = MoveCopyOptions(retain_editor_and_modified_on_move=retain_editor_and_modified)
-            MoveCopyUtil.move_folder_by_path(self.context, self.server_relative_path.DecodedUrl, new_relative_path, opt)
+        def _source_folder_resolved():
+            if isinstance(destination, Folder):
+                destination.ensure_property("ServerRelativePath", _copy_folder_by_path, destination)
+            else:
+                self.context.web.ensure_folder_path(destination).after_execute(_copy_folder_by_path)
 
-        self.ensure_property("ServerRelativePath", _move_folder)
+        self.ensure_properties(["ServerRelativePath", "Name"], _source_folder_resolved)
         return return_type
 
     @property