additional type hints enhancements (folder namespace), #740: fix for copy_to_using_path method

Author: vgrem

examples/sharepoint/folders/copy_folder.py

@@ -1,6 +1,7 @@
 """
 Demonstrates how to copy a folder within a site
 """
+
 from office365.sharepoint.client_context import ClientContext
 from tests import create_unique_name, test_team_site_url, test_user_credentials
 
@@ -10,10 +11,11 @@
 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"))
+# folder_to = ctx.web.default_document_library().root_folder.add(create_unique_name("to"))
+folder_to_url = "/sites/team/Shared Documents/Archive/2001/01"
 
 # copies the folder with a new name
-folder = folder_from.copy_to_using_path(folder_to).execute_query()
+folder = folder_from.copy_to(folder_to_url).execute_query()
 print(
     "Folder has been copied from '{0}' into '{1}'".format(
         folder_from.serverRelativeUrl, folder.serverRelativeUrl
@@ -22,4 +24,4 @@
 
 # clean up
 folder_from.delete_object().execute_query()
-folder_to.delete_object().execute_query()
+folder.delete_object().execute_query()

examples/sharepoint/folders/copy_folder_using_path.py

@@ -0,0 +1,27 @@
+"""
+Demonstrates how to copy a folder using path
+"""
+
+from office365.sharepoint.client_context import ClientContext
+from tests import create_unique_name, test_team_site_url, test_user_credentials
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
+
+# creates a temporary folder first in a Documents library
+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"))
+folder_to_url = "Shared Documents/Archive/2001/01"
+
+# copies the folder with a new name
+folder = folder_from.copy_to_using_path(folder_to_url).execute_query()
+print(
+    "Folder has been copied from '{0}' into '{1}'".format(
+        folder_from.server_relative_path, folder.server_relative_path
+    )
+)
+
+# clean up
+folder_from.delete_object().execute_query()
+folder.delete_object().execute_query()

examples/sharepoint/folders/get_props.py

@@ -0,0 +1,11 @@
+"""
+Get Folder properties
+"""
+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.get_folder_by_server_relative_url("Shared Documents").get().execute_query()
+)
+print(folder.name)

examples/sharepoint/folders/list_folders.py

@@ -1,3 +1,5 @@
+from typing import Callable
+
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.folders.folder import Folder
 from tests import test_client_credentials, test_team_site_url
@@ -6,10 +8,7 @@
 
 
 def enum_folder(parent_folder, action):
-    """
-    :type parent_folder: Folder
-    :type action: (Folder)-> None
-    """
+    # type: (Folder, Callable[[Folder], None]) -> None
     parent_folder.expand(["Folders"]).get().execute_query()
     action(parent_folder)
     for folder in parent_folder.folders:

office365/sharepoint/client_context.py

@@ -689,6 +689,11 @@ def tenant_url(self):
         names[0] = names[0] + "-admin"
         return result.scheme + "://" + ".".join(names)
 
+    @property
+    def site_path(self):
+        root_url = get_absolute_url(self.base_url)
+        return self.base_url.replace(root_url, "")
+
     @property
     def is_tenant(self):
         """

office365/sharepoint/folders/collection.py

@@ -33,6 +33,7 @@ def ensure_path(self, path):
 
         :param str path: server or site relative url to a folder
         """
+        path = path.replace(self.context.site_path, "")
         names = [name for name in path.split("/") if name]
         if not names:
             raise ValueError("Invalid server or site relative url")

office365/sharepoint/folders/folder.py

@@ -1,5 +1,7 @@
 from datetime import datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Optional
+
+from typing_extensions import Self
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value_collection import ClientValueCollection
@@ -20,6 +22,7 @@
 
 if TYPE_CHECKING:
     from office365.sharepoint.files.collection import FileCollection
+    from office365.sharepoint.folders.collection import FolderCollection
 
 
 class Folder(Entity):
@@ -54,17 +57,14 @@ def download_folder(
     def get_files(self, recursive=False):
         """
         Retrieves files
-
         :param bool recursive: Determines whether to enumerate folders recursively
         """
         from office365.sharepoint.files.collection import FileCollection
 
         return_type = FileCollection(self.context, self.files.resource_path, self)
 
         def _loaded(parent):
-            """
-            :type parent: Folder
-            """
+            # type: ("Folder") -> None
             [return_type.add_child(f) for f in parent.files]
             if recursive:
                 for folder in parent.folders:
@@ -94,9 +94,7 @@ def _update_folder(url):
             self.set_property("ServerRelativeUrl", url)
 
         def _move_to(destination_folder):
-            """
-            :type destination_folder: Folder
-            """
+            # type: ("Folder") -> None
             destination_url = "/".join(
                 [destination_folder.serverRelativeUrl, self.name]
             )
@@ -261,10 +259,8 @@ def get_list_item_changes(self, query):
         return return_type
 
     def add(self, name):
-        """Adds the folder that is located under a current folder
-
-        :type name: str
-        """
+        # type: (str) -> Self
+        """Adds the folder that is located under a current folder"""
         return self.folders.add(name)
 
     def rename(self, name):
@@ -352,6 +348,7 @@ def _loaded():
         return return_type
 
     def copy_to(self, destination, keep_both=False, reset_author_and_created=False):
+        # type: (str|"Folder", bool, bool) -> "Folder"
         """Copies the folder with files to the destination URL.
 
         :param str or Folder destination: Parent folder object or server relative folder url
@@ -362,9 +359,7 @@ def copy_to(self, destination, keep_both=False, reset_author_and_created=False):
         self.parent_collection.add_child(return_type)
 
         def _copy_folder(destination_folder):
-            """
-            :type destination_folder: Folder
-            """
+            # type: ("Folder") -> None
             destination_url = "/".join(
                 [destination_folder.serverRelativeUrl, self.name]
             )
@@ -393,6 +388,7 @@ def _source_folder_resolved():
     def copy_to_using_path(
         self, destination, keep_both=False, reset_author_and_created=False
     ):
+        # type: (str|"Folder", bool, bool) -> "Folder"
         """Copies the folder with files to the destination Path.
 
         :param str or Folder destination: Parent folder object or server relative folder url
@@ -404,9 +400,7 @@ def copy_to_using_path(
         self.parent_collection.add_child(return_type)
 
         def _copy_folder_by_path(destination_folder):
-            """
-            :type destination_folder: Folder
-            """
+            # type: ("Folder") -> None
             destination_url = "/".join(
                 [str(destination_folder.server_relative_path), self.name]
             )
@@ -425,9 +419,9 @@ def _source_folder_resolved():
                     "ServerRelativePath", _copy_folder_by_path, destination
                 )
             else:
-                self.context.web.ensure_folder_path(destination).after_execute(
-                    _copy_folder_by_path
-                )
+                self.context.web.ensure_folder_path(destination).get().select(
+                    ["ServerRelativePath"]
+                ).after_execute(_copy_folder_by_path)
 
         self.ensure_properties(["ServerRelativePath", "Name"], _source_folder_resolved)
         return return_type
@@ -444,7 +438,8 @@ def storage_metrics(self):
 
     @property
     def list_item_all_fields(self):
-        """Specifies the list item fields (2) values for the list item corresponding to the folder."""
+        # type: () -> ListItem
+        """Specifies the list item fields values for the list item corresponding to the folder."""
         return self.properties.get(
             "ListItemAllFields",
             ListItem(
@@ -467,6 +462,7 @@ def files(self):
 
     @property
     def folders(self):
+        # type: () -> FolderCollection
         """Specifies the collection of list folders contained within the list folder."""
         from office365.sharepoint.folders.collection import FolderCollection
 
@@ -477,6 +473,7 @@ def folders(self):
 
     @property
     def parent_folder(self):
+        # type: () -> "Folder"
         """Specifies the list folder."""
         return self.properties.get(
             "ParentFolder",
@@ -485,103 +482,85 @@ def parent_folder(self):
 
     @property
     def name(self):
-        """Specifies the list folder name.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the list folder name."""
         return self.properties.get("Name", None)
 
     @property
     def is_wopi_enabled(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether the folder is enabled for WOPI default action.
-
-        :rtype: bool or None
         """
         return self.properties.get("IsWOPIEnabled", None)
 
     @property
     def prog_id(self):
-        """Gets the identifier (ID) of the application in which the folder was created.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the identifier (ID) of the application in which the folder was created."""
         return self.properties.get("ProgID", None)
 
     @property
     def unique_id(self):
-        """Gets the unique ID of the folder.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the unique ID of the folder."""
         return self.properties.get("UniqueId", None)
 
     @property
     def exists(self):
-        """Gets a Boolean value that indicates whether the folder exists.
-
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Gets a Boolean value that indicates whether the folder exists."""
         return self.properties.get("Exists", None)
 
     @property
     def welcome_page(self):
-        """Specifies the server-relative URL for the list folder Welcome page.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the server-relative URL for the list folder Welcome page."""
         return self.properties.get("WelcomePage", None)
 
     @property
     def unique_content_type_order(self):
-        """Specifies the content type order for the list folder.
-
-        :rtype: office365.sharepoint.contenttypes.content_type_id.ContentTypeId or None
-        """
+        """Specifies the content type order for the list folder."""
         return self.properties.get("UniqueContentTypeOrder", ContentTypeId())
 
     @property
     def content_type_order(self):
-        """Specifies the content type order for the list folder.
-
-        :rtype: office365.sharepoint.contenttypes.content_type_id.ContentTypeId or None
-        """
+        """Specifies the content type order for the list folder."""
         return self.properties.get("ContentTypeOrder", ContentTypeId())
 
     @property
     def time_last_modified(self):
-        """Gets the last time this folder or a direct child was modified in UTC.
-
-        :rtype: str or None
-        """
-        return self.properties.get("TimeLastModified", None)
+        # type: () -> Optional[datetime]
+        """Gets the last time this folder or a direct child was modified in UTC."""
+        return self.properties.get("TimeLastModified", datetime.min)
 
     @property
     def time_created(self):
+        # type: () -> Optional[datetime]
         """
         Gets when the folder was created in UTC.
-        :rtype: datetime or None
         """
         return self.properties.get("TimeCreated", datetime.min)
 
     @property
     def serverRelativeUrl(self):
+        # type: () -> Optional[str]
         """
         Gets the server-relative URL of the list folder.
-        :rtype: str or None
         """
         return self.properties.get("ServerRelativeUrl", None)
 
     @property
     def server_relative_path(self):
+        # type: () -> Optional[SPResPath]
         """
         Gets the server-relative Path of the list folder.
-        :rtype: SPResPath or None
         """
         return self.properties.get("ServerRelativePath", SPResPath())
 
     @property
     def property_ref_name(self):
+        # type: () -> str
         return "ServerRelativeUrl"
 
     def get_property(self, name, default_value=None):
@@ -594,6 +573,7 @@ def get_property(self, name, default_value=None):
                 "ServerRelativePath": self.server_relative_path,
                 "StorageMetrics": self.storage_metrics,
                 "TimeCreated": self.time_created,
+                "TimeLastModified": self.time_last_modified,
             }
             default_value = property_mapping.get(name, None)
         return super(Folder, self).get_property(name, default_value)

office365/sharepoint/utilities/move_copy_util.py

@@ -1,10 +1,15 @@
 import os
+from typing import IO, TYPE_CHECKING, Callable
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity import Entity
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
+if TYPE_CHECKING:
+    from office365.sharepoint.files.file import File
+    from office365.sharepoint.folders.folder import Folder
+
 
 class MoveCopyUtil(Entity):
     """A container class for static move/copy methods."""
@@ -141,6 +146,7 @@ def move_folder_by_path(context, src_path, dest_path, options):
     def download_folder(
         remove_folder, download_file, after_file_downloaded=None, recursive=True
     ):
+        # type: (Folder, IO, Callable[[File], None], bool) -> Folder
         """
         Downloads a folder into a zip file
         :param office365.sharepoint.folders.folder.Folder remove_folder: Parent folder