Office365-REST-Python-Client 2.6.2__py3-none-any.whl → 3.1.0__py3-none-any.whl

office365/sharepoint/folders/folder.py

@@ -1,20 +1,30 @@
+from __future__ import annotations
+
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Callable, Iterable, List, Optional, Tuple, Union
 
 from typing_extensions import Self
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value_collection import ClientValueCollection
+from office365.runtime.operations import Progress, ProgressCallback
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.queries.update_entity import UpdateEntityQuery
+from office365.runtime.types.odata_property import odata
 from office365.sharepoint.changes.collection import ChangeCollection
 from office365.sharepoint.changes.query import ChangeQuery
 from office365.sharepoint.contenttypes.content_type_id import ContentTypeId
 from office365.sharepoint.entity import Entity
+from office365.sharepoint.folders.delete_parameters import FolderDeleteParameters
 from office365.sharepoint.listitems.listitem import ListItem
+from office365.sharepoint.permissions.base_permissions import BasePermissions
+from office365.sharepoint.principal.users.user import User
 from office365.sharepoint.sharing.document_manager import DocumentSharingManager
 from office365.sharepoint.sharing.links.share_response import ShareLinkResponse
+from office365.sharepoint.sharing.object_sharing_information import ObjectSharingInformation
+from office365.sharepoint.sharing.user_role_assignment import UserRoleAssignment
 from office365.sharepoint.sharing.user_sharing_result import UserSharingResult
 from office365.sharepoint.storagemetrics.storage_metrics import StorageMetrics
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
@@ -23,23 +33,27 @@ from office365.sharepoint.utilities.move_copy_util import MoveCopyUtil
 
 if TYPE_CHECKING:
     from office365.sharepoint.files.collection import FileCollection
+    from office365.sharepoint.files.file import File
     from office365.sharepoint.folders.collection import FolderCollection
 
+_DEFAULT_CHUNK_SIZE = 4 * 1024 * 1024  # simple-upload threshold / upload-session chunk
+
 
 class Folder(Entity):
-    """Represents a folder in a SharePoint Web site."""
+    """Represents a folder in a SharePoint Website."""
 
     def __str__(self):
         return self.name or self.entity_type_name
 
     def __repr__(self):
-        return self.serverRelativeUrl or self.unique_id or self.entity_type_name
+        return self.server_relative_url or self.unique_id or self.entity_type_name
 
     @staticmethod
-    def from_url(abs_url):
-        """
-        Addresses a Folder by absolute url
-        :type abs_url: str
+    def from_url(abs_url: str):
+        """Addresses a Folder by absolute url
+
+        Args:
+            abs_url (str):
         """
         from office365.sharepoint.client_context import ClientContext
 
@@ -47,246 +61,349 @@ class Folder(Entity):
         relative_url = abs_url.replace(ctx.base_url, "")
         return ctx.web.get_folder_by_server_relative_url(relative_url)
 
-    def download_folder(
-        self, download_file, after_file_downloaded=None, recursive=True
+    def download_folder_as_zip(
+        self,
+        download_file: Union[str, Path, IO],
+        after_file_downloaded: Optional[Callable[[File], None]] = None,
+        recursive: bool = True,
+        include_versions: bool = False,
+        progress: Optional[ProgressCallback] = None,
     ):
+        """Downloads a folder into a zip file
+
+        Args:
+            download_file (str or pathlib.Path or IO): Destination zip (a path or
+              a seekable file object).
+            after_file_downloaded ((office365.sharepoint.files.file.File)->None): A download callback
+            recursive (bool): Determines whether to traverse folders recursively
+            include_versions (bool): If True, also downloads each file's version history
+              into the zip under ``versions/{path}/v{label}``
+            progress: Optional hook invoked per downloaded file with a
+              ``Progress`` snapshot.
         """
-        Downloads a folder into a zip file
-        :param typing.IO download_file: A download zip file object
-        :param (office365.sharepoint.files.file.File)->None after_file_downloaded: A download callback
-        :param bool recursive: Determines whether to traverse folders recursively
-        """
-        return MoveCopyUtil.download_folder(
-            self, download_file, after_file_downloaded, recursive
+        return MoveCopyUtil.download_folder_as_zip(
+            self, download_file, after_file_downloaded, recursive, include_versions, progress
         )
 
-    def get_folders(self, recursive=False):
-        """
-        Retrieves folders
-        :param bool recursive: Determines whether to enumerate folders recursively
+    def download_folder(
+        self,
+        download_file: Union[str, Path, IO],
+        after_file_downloaded: Optional[Callable[[File], None]] = None,
+        recursive: bool = True,
+        include_versions: bool = False,
+        progress: Optional[ProgressCallback] = None,
+    ):
+        """Deprecated alias of :meth:`download_folder_as_zip`."""
+        return self.download_folder_as_zip(download_file, after_file_downloaded, recursive, include_versions, progress)
+
+    def upload_folder(
+        self,
+        source: Union[str, Path, Iterable[Union[str, Path, Tuple[str, Union[str, Path, bytes]]]]],
+        after_file_uploaded: Optional[Callable[[File], None]] = None,
+        recursive: bool = True,
+        progress: Optional[ProgressCallback] = None,
+        chunk_size: int = _DEFAULT_CHUNK_SIZE,
+    ):
+        """Upload a local directory / files into this folder — sequential, deferred.
+
+        Counterpart of :meth:`download_folder_as_zip`; see
+        :meth:`MoveCopyUtil.upload_folder` for the ``source`` forms (directory,
+        file, list of file paths, or ``(relative_path, content)`` pairs).
+
+        Args:
+            source: Local directory / file / file list / (path, content) pairs.
+            after_file_uploaded ((office365.sharepoint.files.file.File)->None): Per-file callback.
+            recursive (bool): Traverse subdirectories when ``source`` is a directory.
+            progress: Optional hook invoked per uploaded file with a ``Progress`` snapshot.
+            chunk_size (int): Upload-session chunk size / size threshold (bytes).
+
+        Returns:
+            The target folder (chainable).
         """
-        from office365.sharepoint.folders.collection import FolderCollection  # noqa
+        return MoveCopyUtil.upload_folder(self, source, after_file_uploaded, recursive, progress, chunk_size)
 
-        return_type = FolderCollection(self.context, self.folders.resource_path, self)
+    def upload_folder_from_zip(
+        self,
+        source_zip: Union[str, Path, IO],
+        after_file_uploaded: Optional[Callable[[File], None]] = None,
+        progress: Optional[ProgressCallback] = None,
+        chunk_size: int = _DEFAULT_CHUNK_SIZE,
+    ):
+        """Upload a zip archive's file/folder hierarchy into this folder.
 
-        def _get_folders(parent):
-            # type: ("Folder") -> None
-            [return_type.add_child(f) for f in parent.folders]
-            if recursive:
-                for folder in parent.folders:
-                    folder.ensure_properties(["Folders"], _get_folders, parent=folder)
+        Counterpart of :meth:`download_folder_as_zip`; see
+        :meth:`MoveCopyUtil.upload_folder_from_zip`. Entries are read in memory,
+        one at a time, and uploaded at their literal relative paths (deferred).
 
-        self.ensure_properties(["Folders"], _get_folders, parent=self)
-        return return_type
+        Args:
+            source_zip (str or pathlib.Path or IO): A zip archive (path or file object).
+            after_file_uploaded ((office365.sharepoint.files.file.File)->None): Per-file callback.
+            progress: Optional hook invoked per uploaded file with a ``Progress`` snapshot.
+            chunk_size (int): Upload-session chunk size / size threshold (bytes).
 
-    def get_files(self, recursive=False):
+        Returns:
+            The target folder (chainable).
         """
-        Retrieves files
-        :param bool recursive: Determines whether to enumerate folders recursively
+        return MoveCopyUtil.upload_folder_from_zip(self, source_zip, after_file_uploaded, progress, chunk_size)
+
+    def get_user_effective_permissions(self, user: str | User) -> ClientResult[BasePermissions]:
+        """Returns the user permissions for a folder"""
+        return self.list_item_all_fields.get_user_effective_permissions(user)
+
+    def get_folders(
+        self,
+        recursive: bool = False,
+        progress: Optional[Callable[[Progress[Folder]], None]] = None,
+    ) -> FolderCollection:
+        """Retrieves folders
+
+        Args:
+            recursive (bool): Determines whether to enumerate folders recursively
+            progress: Optional hook invoked per scanned folder with a
+              ``Progress[Folder]`` snapshot (``done`` = folders discovered so
+              far; ``items`` = the folders found in the folder just scanned).
+
+        The fluent ``.select([...])`` / ``.expand([...])`` applied to the returned
+        collection is honored on every per-folder load.
         """
-        from office365.sharepoint.files.collection import FileCollection  # noqa
+        from office365.runtime.queries.deferred import DeferredOperationQuery
+        from office365.sharepoint.folders.collection import FolderCollection
 
-        return_type = FileCollection(self.context, self.files.resource_path, self)
+        return_type = FolderCollection(self.context, self.folders.resource_path, self)
 
-        def _get_files(parent):
-            # type: ("Folder") -> None
-            [return_type.add_child(f) for f in parent.files]
-            if recursive:
-                for folder in parent.folders:
-                    folder.ensure_properties(
-                        ["Files", "Folders"], _get_files, parent=folder
-                    )
+        def _get_folders(parent: Folder) -> None:
+            def _on_loaded(folders) -> None:
+                for folder in folders:
+                    return_type.add_child(folder)
+                if callable(progress):
+                    progress(Progress(done=len(return_type), stage="scanning", items=list(folders)))
+                if recursive:
+                    for folder in folders:
+                        _get_folders(folder)
+
+            child_folders = parent.folders
+            return_type.query_options.apply_to(child_folders)
+            if return_type.query_options.select:
+                fields = sorted({"Id", "Name", "ServerRelativeUrl"} | set(return_type.query_options.select))
+                child_folders.select(fields)
+            child_folders.get().after_execute(_on_loaded)
+
+        placeholder = DeferredOperationQuery(self.context)
+        self.context.add_query(placeholder).after_execute(lambda _: _get_folders(self))
+        return return_type
 
-        self.ensure_properties(["Files", "Folders"], _get_files, parent=self)
+    def get_files(
+        self,
+        recursive: bool = False,
+        progress: Optional[Callable[[Progress[File]], None]] = None,
+    ) -> FileCollection:
+        """Retrieves files
+
+        Args:
+            recursive (bool): Determines whether to enumerate folders recursively
+            progress: Optional hook invoked per scanned folder with a
+              ``Progress[File]`` snapshot (``done`` = files discovered so far;
+              ``items`` = the files found in the folder just scanned).
+
+        The fluent ``.select([...])`` / ``.expand([...])`` applied to the returned
+        collection is honored on every per-folder file load.
+        """
+        from office365.runtime.queries.deferred import DeferredOperationQuery
+        from office365.sharepoint.files.collection import FileCollection
+
+        resource_path = self.files.resource_path
+        assert resource_path is not None
+        return_type = FileCollection(self.context, resource_path, self)
+
+        def _get_files(parent: Folder) -> None:
+            def _on_files_loaded(col) -> None:
+                for file in col:
+                    return_type.add_child(file)
+                if callable(progress):
+                    progress(Progress(done=len(return_type), stage="scanning", items=list(col)))
+                if recursive:
+                    subfolders = parent.folders
+                    subfolders.get().after_execute(lambda _: [_get_files(folder) for folder in subfolders])
+
+            files = parent.files
+            return_type.query_options.apply_to(files)
+            if return_type.query_options.select:
+                fields = sorted({"Id", "Name", "ServerRelativeUrl"} | set(return_type.query_options.select))
+                files.select(fields)
+            files.get().after_execute(_on_files_loaded)
+
+        placeholder = DeferredOperationQuery(self.context)
+        self.context.add_query(placeholder).after_execute(lambda _: _get_files(self))
         return return_type
 
-    def get_sharing_information(self):
+    def get_sharing_information(self) -> ObjectSharingInformation:
         """Gets the sharing information for a folder."""
         return self.list_item_all_fields.get_sharing_information()
 
-    def move_to(self, destination):
-        """
-        Moves the folder and its contents under a new folder at the specified destination.
+    def move_to(self, destination: Union[str, Folder]) -> Self:
+        """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 or Folder destination: Specifies the server relative url or an existing folder
-            where to move a folder.
+        Args:
+            destination (str or Folder): Specifies the server relative url or an existing folder where to move a folder.
         """
 
-        def _move_to(destination_folder):
-            # type: ("Folder") -> None
-            destination_url = "/".join(
-                [destination_folder.serverRelativeUrl, self.name]
-            )
+        def _move_to(destination_folder: Folder) -> None:
+            destination_url = "/".join([x or "" for x in [destination_folder.server_relative_url, self.name]])
             qry = ServiceOperationQuery(self, "MoveTo", {"newUrl": destination_url})
 
-            def _update_folder(return_type):
+            def _update_folder(_):
                 self.set_property("ServerRelativeUrl", destination_url)
 
-            self.context.add_query(qry).after_query_execute(_update_folder)
+            self.context.add_query(qry).after_execute(_update_folder)
 
         def _source_folder_resolved():
             if isinstance(destination, Folder):
-                destination.ensure_property("ServerRelativeUrl", _move_to, destination)
+                dest = destination
+                destination.ensure_property("ServerRelativeUrl").after_execute(lambda _: _move_to(dest))
             else:
                 self.context.web.ensure_folder_path(destination).after_execute(_move_to)
 
-        self.ensure_properties(["ServerRelativeUrl", "Name"], _source_folder_resolved)
+        self.ensure_properties(["ServerRelativeUrl", "Name"]).after_execute(lambda _: _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.
+    def move_to_using_path(self, destination: Union[str, Folder]) -> Self:
+        """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.
+        Args:
+            destination (str or Folder): Specifies the server relative url or an existing folder where to move a folder.
         """
 
-        def _move_to_using_path(destination_folder):
-            # type: ("Folder") -> None
-            destination_path = "/".join(
-                [str(destination_folder.server_relative_path), self.name]
-            )
-            qry = ServiceOperationQuery(
-                self, "MoveToUsingPath", {"DecodedUrl": destination_path}
-            )
+        def _move_to_using_path(destination_folder: Folder) -> None:
+            destination_path = "/".join([x or "" for x in [str(destination_folder.server_relative_path), self.name]])
+            qry = ServiceOperationQuery(self, "MoveToUsingPath", {"DecodedUrl": destination_path})
 
             def _update_folder(url):
                 self.set_property("ServerRelativePath", destination_path)
 
-            self.context.add_query(qry).after_query_execute(_update_folder)
+            self.context.add_query(qry).after_execute(_update_folder)
 
         def _source_folder_resolved():
             if isinstance(destination, Folder):
-                destination.ensure_property(
-                    "ServerRelativePath", _move_to_using_path, destination
-                )
+                dest = destination
+                destination.ensure_property("ServerRelativePath").after_execute(lambda _: _move_to_using_path(dest))
             else:
-                self.context.web.ensure_folder_path(destination).after_execute(
-                    _move_to_using_path
-                )
+                self.context.web.ensure_folder_path(destination).after_execute(_move_to_using_path)
 
-        self.ensure_properties(["ServerRelativePath", "Name"], _source_folder_resolved)
+        self.ensure_properties(["ServerRelativePath", "Name"]).after_execute(lambda _: _source_folder_resolved())
         return self
 
     def move_to_using_path_with_parameters(
-        self, new_relative_path, retain_editor_and_modified=False
-    ):
+        self, new_relative_path: str, retain_editor_and_modified: bool = False
+    ) -> Folder:
         """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:
+        Args:
+            new_relative_path (str): A full URL path that represents the destination folder.
+            retain_editor_and_modified (bool):
         """
         return_type = Folder(self.context)
         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_by_path(
-                self.context,
-                self.server_relative_path.DecodedUrl,
-                new_relative_path,
-                opt,
-            )
+            opt = MoveCopyOptions(RetainEditorAndModifiedOnMove=retain_editor_and_modified)
+            assert self.server_relative_path is not None
+            MoveCopyUtil.move_folder_by_path(self.context, self.server_relative_path.DecodedUrl, new_relative_path, opt)
 
-        self.ensure_property("ServerRelativePath", _move_folder)
+        self.ensure_property("ServerRelativePath").after_execute(lambda _: _move_folder())
         return return_type
 
-    def share_link(self, link_kind, expiration=None, role=None, password=None):
-        # type: (int, Optional[datetime], Optional[int], Optional[str]) -> ClientResult[ShareLinkResponse]
+    def share_link(
+        self,
+        link_kind: int,
+        expiration: Optional[datetime] = None,
+        role: Optional[int] = None,
+        password: Optional[str] = None,
+    ) -> ClientResult[ShareLinkResponse]:
         """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.
 
-        :param link_kind: The kind of the tokenized sharing link to be created/updated or retrieved.
-        :param expiration: A date/time string for which the format conforms to the ISO 8601:2004(E)
-            complete representation for calendar date and time of day and which represents the time and date of expiry
-            for the tokenized sharing link. Both the minutes and hour value MUST be specified for the difference
-            between the local and UTC time. Midnight is represented as 00:00:00. A null value indicates no expiry.
-            This value is only applicable to tokenized sharing links that are anonymous access links.
-        :param role: The role to be used for the tokenized sharing link. This is required for Flexible links
-            and ignored for all other kinds.
-        :param password: Optional password value to apply to the tokenized sharing link,
-            if it can support password protection.
+        Args:
+            link_kind: The kind of the tokenized sharing link to be created/updated or retrieved.
+            expiration: A date/time string for which the format conforms to the ISO 8601:2004(E) complete representation
+                for calendar date and time of day and which represents the time and date of expiry for the tokenized
+                sharing link. Both the minutes and hour value MUST be specified for the difference between the local and
+                UTC time. Midnight is represented as 00:00:00. A null value indicates no expiry. This value is only
+                applicable to tokenized sharing links that are anonymous access links.
+            role: The role to be used for the tokenized sharing link. This is required for Flexible links and ignored
+                for all other kinds.
+            password: Optional password value to apply to the tokenized sharing link, if it can support password
+                protection.
         """
         return self.list_item_all_fields.share_link(
             link_kind=link_kind, expiration=expiration, role=role, password=password
         )
 
-    def unshare_link(self, link_kind, share_id=None):
-        """
-        Removes the specified tokenized sharing link of the folder.
+    def unshare_link(self, link_kind: int, share_id: Optional[str] = None) -> Self:
+        """Removes the specified tokenized sharing link of the folder.
 
-        :param int link_kind: This optional value specifies the globally unique identifier (GUID) of the tokenized
-            sharing link that is intended to be removed.
-        :param str or None share_id: The kind of tokenized sharing link that is intended to be removed.
+        Args:
+            link_kind (int): This optional value specifies the globally unique identifier (GUID) of the tokenized
+                sharing link that is intended to be removed.
+            share_id (str or None): The kind of tokenized sharing link that is intended to be removed.
         """
-        return self.list_item_all_fields.unshare_link(link_kind, share_id)
+        return self.list_item_all_fields.unshare_link(link_kind, share_id)  # type: ignore[returnType]
 
-    def recycle(self):
+    def recycle(self) -> ClientResult[str]:
         """Moves the folder to the Recycle Bin and returns the identifier of the new Recycle Bin item."""
-
-        return_type = ClientResult(self.context)
+        return_type = ClientResult(self.context, str())
         qry = ServiceOperationQuery(self, "Recycle", None, None, None, return_type)
         self.context.add_query(qry)
         return return_type
 
-    def recycle_with_parameters(self, parameters):
-        """
-        Moves the list folder to the Recycle Bin and returns the identifier of the new Recycle Bin item
+    def recycle_with_parameters(self, parameters: FolderDeleteParameters) -> ClientResult[str]:
+        """Moves the list folder to the Recycle Bin and returns the identifier of the new Recycle Bin item
 
-        :type parameters: office365.sharepoint.folders.delete_parameters.FolderDeleteParameters
+        Args:
+            parameters (FolderDeleteParameters):
         """
-        return_type = ClientResult(self.context)
+        return_type = ClientResult(self.context, str())
         payload = {"parameters": parameters}
-        qry = ServiceOperationQuery(
-            self, "RecycleWithParameters", None, payload, None, return_type
-        )
+        qry = ServiceOperationQuery(self, "RecycleWithParameters", None, payload, None, return_type)
         self.context.add_query(qry)
         return return_type
 
-    def get_changes(self, query=None):
+    def get_changes(self, query: Optional[ChangeQuery] = None) -> ChangeCollection:
         """Returns the collection of changes from the change log that have occurred within the folder,
-           based on the specified query.
+        based on the specified query.
 
-        :param office365.sharepoint.changes.query.ChangeQuery query: Specifies which changes to return
+        Args:
+            query (ChangeQuery): Specifies which changes to return
         """
         if query is None:
-            query = ChangeQuery(folder=True)
+            query = ChangeQuery(Folder=True)
         return_type = ChangeCollection(self.context)
         payload = {"query": query}
-        qry = ServiceOperationQuery(
-            self, "getChanges", None, payload, None, return_type
-        )
+        qry = ServiceOperationQuery(self, "getChanges", None, payload, None, return_type)
         self.context.add_query(qry)
         return return_type
 
-    def get_list_item_changes(self, query):
-        """
-        Gets the collection of all changes from the change log that have occurred within the scope of the SharePoint
+    def get_list_item_changes(self, query: ChangeQuery) -> ChangeCollection:
+        """Gets the collection of all changes from the change log that have occurred within the scope of the SharePoint
         folder based on the specified query.
 
-        :param office365.sharepoint.changes.query.ChangeQuery query: Specifies which changes to return
+        Args:
+            query (ChangeQuery): Specifies which changes to return
         """
         return_type = ChangeCollection(self.context)
         payload = {"query": query}
-        qry = ServiceOperationQuery(
-            self, "getListItemChanges", None, payload, None, return_type
-        )
+        qry = ServiceOperationQuery(self, "getListItemChanges", None, payload, None, return_type)
         self.context.add_query(qry)
         return return_type
 
-    def add(self, name):
-        # type: (str) -> Self
+    def add(self, name: str) -> Self:
         """Adds the folder that is located under a current folder"""
-        return self.folders.add(name)
+        return self.folders.add(name)  # type: ignore[returnType]
 
-    def rename(self, name):
-        # type: (str) -> Self
+    def rename(self, name: str) -> Self:
         """Rename a Folder resource"""
         item = self.list_item_all_fields
         item.set_property("Title", name)
@@ -295,62 +412,86 @@ class Folder(Entity):
         self.context.add_query(qry)
         return self
 
-    def upload_file(self, file_name, content):
-        """Uploads a file into folder.
-        Note: This method only supports files up to 4MB in size!
-
-        :param str file_name: Specifies the URL of the file to be added
-        :param str or bytes content: Specifies the binary content of the file to be added.
+    def upload_file(
+        self,
+        relative_path: str,
+        content: Union[str, bytes],
+        chunk_size: int = _DEFAULT_CHUNK_SIZE,
+        progress: Optional[ProgressCallback] = None,
+    ) -> File:
+        """Upload content to a path relative to this folder, creating folders as needed.
+
+        A plain ``file_name`` (no slashes) uploads directly into this folder;
+        a nested ``relative_path`` ensures the parent folders first. Content is
+        uploaded with the size-dispatching :meth:`FileCollection.upload_content`
+        (simple upload up to ``chunk_size``, resumable session above). The
+        returned :class:`File` is deferred — the caller executes it.
+
+        Args:
+            relative_path (str): File name, or a path relative to this folder,
+              e.g. ``"report.pdf"`` or ``"Projects/2026/report.pdf"``.
+            content (str or bytes): Specifies the binary content of the file to be added.
+            chunk_size (int): Upload-session chunk size / size threshold (bytes).
+            progress: Optional hook invoked with a ``Progress`` snapshot
+              (``done``/``total`` in bytes) while the file uploads.
         """
-        return self.files.add(file_name, content, True)
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        parts = relative_path.split("/")
+        folder = self
+        if len(parts) > 1:
+            folder = self.ensure_folder("/".join(parts[:-1]))
+        return folder.files.upload_content(content, parts[-1], chunk_size, progress)
 
     def update_document_sharing_info(
         self,
-        user_role_assignments,
-        validate_existing_permissions=None,
-        additive_mode=None,
-        send_server_managed_notification=None,
-        custom_message=None,
-        include_anonymous_links_in_notification=None,
-        propagate_acl=None,
-    ):
-        """
-        This method allows a caller with the 'ManagePermission' permission to update sharing information about a
+        user_role_assignments: List[UserRoleAssignment],
+        validate_existing_permissions: Optional[bool] = None,
+        additive_mode: Optional[bool] = None,
+        send_server_managed_notification: Optional[bool] = None,
+        custom_message: Optional[str] = None,
+        include_anonymous_links_in_notification: Optional[bool] = None,
+        propagate_acl: Optional[bool] = None,
+    ) -> ClientResult[ClientValueCollection[UserSharingResult]]:
+        """This method allows a caller with the 'ManagePermission' permission to update sharing information about a
         document to enable document sharing with a set of users. It returns an array of
         UserSharingResult (section 3.2.5.190) elements where each element contains the sharing status for each user.
 
-        :param list[UserRoleAssignment] user_role_assignments:An array of recipients and assigned roles on the securable
-            object pointed to by the resourceAddress parameter.
-        :param bool validate_existing_permissions: A Boolean flag indicating how to honor a requested permission
-            for a user. If this value is "true", the protocol server will not grant the requested permission if a user
-            already has sufficient permissions, and if this value is "false", the protocol server will grant the
-            requested permission whether or not a user already has the same or more permissions.
-            This parameter is applicable only when the parameter additiveMode is set to true.
-        :param bool additive_mode: A Boolean flag indicating whether the permission setting uses the additive or strict
-            mode. If this value is "true", the permission setting uses the additive mode, which means that the
-            specified permission will be added to the user's current list of permissions if it is not there already,
-            and if this value is "false", the permission setting uses the strict mode, which means that the specified
-            permission will replace the user's current permissions.
-        :param bool send_server_managed_notification: A Boolean flag to indicate whether or not to generate an email
-            notification to each recipient in the "userRoleAssignments" array after the document update is completed
-            successfully. If this value is "true", the protocol server will send an email notification if an email
-            server is configured, and if the value is "false", no email notification will be sent.
-        :param str custom_message: A custom message to be included in the email notification.
-        :param bool include_anonymous_links_in_notification: A Boolean flag that indicates whether or not to include
-            anonymous access links in the email notification to each recipient in the userRoleAssignments array after
-            the document update is completed successfully. If the value is "true", the protocol server will include
-            an anonymous access link in the email notification, and if the value is "false", no link will be included.
-        :param bool propagate_acl: A flag to determine if permissions SHOULD be pushed to items with unique permission.
+        Args:
+            user_role_assignments (list[UserRoleAssignment]): An array of recipients and assigned roles on the securable
+                object pointed to by the resourceAddress parameter.
+            validate_existing_permissions (bool): A Boolean flag indicating how to honor a requested permission for a
+                user.
+                If this value is "true", the protocol server will not grant the
+                requested permission if a user already has sufficient permissions, and
+                if this value is "false", the protocol server will grant the requested
+                permission whether or not a user already has the same or more
+                permissions. This parameter is applicable only when the parameter additiveMode is set to true.
+            additive_mode (bool): A Boolean flag indicating whether the permission setting uses the additive or strict
+                mode.
+                If this value is "true", the permission setting uses the additive mode, which means
+                that the specified permission will be added to the user's current list of permissions
+                if it is not there already, and if this value is "false", the permission setting uses
+                the strict mode, which means that the specified permission will replace the user's current permissions.
+            send_server_managed_notification (bool): A Boolean flag to indicate whether or not to generate an email
+                notification to each recipient in the "userRoleAssignments" array
+                after the document update is completed successfully.
+                If this value is "true", the protocol server will send an email
+                notification if an email server is configured, and if the value is
+                "false", no email notification will be sent.
+            custom_message (str): A custom message to be included in the email notification.
+            include_anonymous_links_in_notification (bool): A Boolean flag that indicates whether or not to include
+                anonymous access links in the email notification to each
+                recipient in the userRoleAssignments array after the
+                document update is completed successfully.
+                If the value is "true", the protocol server will include an
+                anonymous access link in the email notification, and if the value is "false", no link will be included.
+            propagate_acl (bool): A flag to determine if permissions SHOULD be pushed to items with unique permission.
         """
+        return_type = ClientResult(self.context, ClientValueCollection(UserSharingResult))
 
-        return_type = ClientResult(
-            self.context, ClientValueCollection(UserSharingResult)
-        )
-
-        def _loaded():
-            resource_address = SPResPath.create_absolute(
-                self.context.base_url, str(self.server_relative_path)
-            )
+        def _update_document_sharing_info():
+            resource_address = SPResPath.create_absolute(self.context.base_url, str(self.server_relative_path))
             DocumentSharingManager.update_document_sharing_info(
                 self.context,
                 str(resource_address),
@@ -364,247 +505,219 @@ class Folder(Entity):
                 return_type,
             )
 
-        self.ensure_property("ServerRelativePath", _loaded)
+        self.ensure_property("ServerRelativePath").after_execute(lambda _: _update_document_sharing_info())
         return return_type
 
-    def copy_to(self, destination, keep_both=False, reset_author_and_created=False):
-        # type: (str|"Folder", bool, bool) -> "Folder"
+    def copy_to(
+        self, destination: Union[str, Folder], keep_both: bool = False, reset_author_and_created: bool = False
+    ) -> Folder:
         """Copies the folder with files to the destination 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:
+        Args:
+            destination (str or Folder): Parent folder object or server relative folder url
+            keep_both (bool): bool
+            reset_author_and_created (bool):
         """
         return_type = Folder(self.context)
+        assert self.parent_collection is not None
         self.parent_collection.add_child(return_type)
 
-        def _copy_to(destination_folder):
-            # type: ("Folder") -> None
-            destination_url = "/".join(
-                [destination_folder.serverRelativeUrl, self.name]
-            )
+        def _copy_to(destination_folder: Folder) -> None:
+            destination_url = "/".join([x or "" for x in [destination_folder.server_relative_url, 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, destination_url, opts
-            )
+            opts = MoveCopyOptions(KeepBoth=keep_both, ResetAuthorAndCreatedOnCopy=reset_author_and_created)
+            MoveCopyUtil.copy_folder(self.context, self.server_relative_url, destination_url, opts)
 
         def _source_folder_resolved():
             if isinstance(destination, Folder):
-                destination.ensure_property("ServerRelativeUrl", _copy_to, destination)
+                dest = destination
+                destination.ensure_property("ServerRelativeUrl").after_execute(lambda _: _copy_to(dest))
             else:
                 self.context.web.ensure_folder_path(destination).after_execute(_copy_to)
 
-        self.ensure_properties(["ServerRelativeUrl", "Name"], _source_folder_resolved)
+        self.ensure_properties(["ServerRelativeUrl", "Name"]).after_execute(lambda _: _source_folder_resolved())
         return return_type
 
     def copy_to_using_path(
-        self, destination, keep_both=False, reset_author_and_created=False
-    ):
-        # type: (str|"Folder", bool, bool) -> "Folder"
+        self, destination: Union[str, Folder], keep_both: bool = False, reset_author_and_created: bool = False
+    ) -> Folder:
         """Copies the folder with files to the destination Path.
 
-        :param str or Folder destination: Parent folder object or server relative folder url
-        :type keep_both: bool
-        :type reset_author_and_created: bool
+        Args:
+            destination (str or Folder): Parent folder object or server relative folder url
+            keep_both (bool):
+            reset_author_and_created (bool):
         """
-
         return_type = Folder(self.context)
+        assert self.parent_collection is not None
         self.parent_collection.add_child(return_type)
 
-        def _copy_folder_by_path(destination_folder):
-            # type: ("Folder") -> None
-            destination_url = "/".join(
-                [str(destination_folder.server_relative_path), self.name]
-            )
+        def _copy_folder_by_path(destination_folder: Folder) -> None:
+            destination_url = "/".join([x or "" for x in [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), destination_url, opts
-            )
+            opts = MoveCopyOptions(KeepBoth=keep_both, ResetAuthorAndCreatedOnCopy=reset_author_and_created)
+            MoveCopyUtil.copy_folder_by_path(self.context, str(self.server_relative_path), destination_url, opts)
 
         def _source_folder_resolved():
             if isinstance(destination, Folder):
-                destination.ensure_property(
-                    "ServerRelativePath", _copy_folder_by_path, destination
-                )
+                dest = destination
+                destination.ensure_property("ServerRelativePath").after_execute(lambda _: _copy_folder_by_path(dest))
             else:
-                self.context.web.ensure_folder_path(destination).get().select(
-                    ["ServerRelativePath"]
-                ).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)
+        self.ensure_properties(["ServerRelativePath", "Name"]).after_execute(lambda _: _source_folder_resolved())
         return return_type
 
+    @odata(name="StorageMetrics")
     @property
-    def storage_metrics(self):
-        # type: () -> StorageMetrics
+    def storage_metrics(self) -> StorageMetrics:
         """Specifies the storage-related metrics for list folders in the site"""
         return self.properties.get(
-            "StorageMetrics",
-            StorageMetrics(
-                self.context, ResourcePath("StorageMetrics", self.resource_path)
-            ),
+            "StorageMetrics", StorageMetrics(self.context, ResourcePath("StorageMetrics", self.resource_path))
         )
 
+    @odata(name="ListItemAllFields")
     @property
-    def list_item_all_fields(self):
-        # type: () -> ListItem
+    def list_item_all_fields(self) -> ListItem:
         """Specifies the list item fields values for the list item corresponding to the folder."""
         return self.properties.get(
-            "ListItemAllFields",
-            ListItem(
-                self.context, ResourcePath("ListItemAllFields", self.resource_path)
-            ),
+            "ListItemAllFields", ListItem(self.context, ResourcePath("ListItemAllFields", self.resource_path))
         )
 
     @property
-    def files(self):
-        # type: () -> FileCollection
+    def files(self) -> FileCollection:
         """Specifies the collection of files contained in the list folder."""
-        from office365.sharepoint.files.collection import FileCollection  # noqa
+        from office365.sharepoint.files.collection import FileCollection
 
         return self.properties.get(
-            "Files",
-            FileCollection(
-                self.context, ResourcePath("Files", self.resource_path), self
-            ),
+            "Files", FileCollection(self.context, ResourcePath("Files", self.resource_path), self)
         )
 
     @property
-    def folders(self):
-        # type: () -> FolderCollection
+    def folders(self) -> FolderCollection:
         """Specifies the collection of list folders contained within the list folder."""
-        from office365.sharepoint.folders.collection import FolderCollection  # noqa
+        from office365.sharepoint.folders.collection import FolderCollection
 
         return self.properties.get(
-            "Folders",
-            FolderCollection(
-                self.context, ResourcePath("Folders", self.resource_path), self
-            ),
+            "Folders", FolderCollection(self.context, ResourcePath("Folders", self.resource_path), self)
         )
 
+    def ensure_folder(self, relative_path: str) -> Folder:
+        """Ensure a nested folder tree exists under this folder.
+
+        A folder-level mirror of :meth:`Web.ensure_folder_path` — creates any
+        missing intermediate folders along a path relative to this folder
+        (deferred; the caller executes the query).
+
+        Args:
+            relative_path (str): Path relative to this folder, e.g. ``"Projects/2026"``.
+        """
+        return self.folders.ensure_by_path(relative_path)
+
+    def ensure_folders(self, relative_paths: Iterable[str]) -> Folder:
+        """Ensure a set of nested folder paths under this folder — deduplicated.
+
+        Since :meth:`ensure_folder` already creates intermediate folders for a
+        nested path, only the *deepest* paths are ensured: a path that is an
+        ancestor of another is covered by it. All ensures are queued as one
+        deferred batch; the caller executes them in a single round-trip.
+        Returns ``self`` for chaining.
+
+        Args:
+            relative_paths (Iterable[str]): Paths relative to this folder.
+        """
+        paths = sorted(set(relative_paths))
+        deepest = [path for path in paths if not any(other.startswith(f"{path}/") for other in paths if other != path)]
+        for path in deepest:
+            self.ensure_folder(path)
+        return self
+
+    @odata(name="ParentFolder")
     @property
-    def parent_folder(self):
-        # type: () -> "Folder"
+    def parent_folder(self) -> Folder:
         """Specifies the list folder."""
         return self.properties.get(
-            "ParentFolder",
-            Folder(self.context, ResourcePath("ParentFolder", self.resource_path)),
+            "ParentFolder", Folder(self.context, ResourcePath("ParentFolder", self.resource_path))
         )
 
     @property
-    def name(self):
-        # type: () -> Optional[str]
+    def name(self) -> Optional[str]:
         """Specifies the list folder name."""
         return self.properties.get("Name", None)
 
     @property
-    def is_wopi_enabled(self):
-        # type: () -> Optional[bool]
+    def is_wopi_enabled(self) -> Optional[bool]:
         """Indicates whether the folder is enabled for WOPI default action."""
         return self.properties.get("IsWOPIEnabled", None)
 
     @property
-    def prog_id(self):
-        # type: () -> Optional[str]
+    def prog_id(self) -> 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):
-        # type: () -> Optional[str]
+    def unique_id(self) -> Optional[str]:
         """Gets the unique ID of the folder."""
         return self.properties.get("UniqueId", None)
 
     @property
-    def exists(self):
-        # type: () -> Optional[bool]
+    def exists(self) -> Optional[bool]:
         """Gets a Boolean value that indicates whether the folder exists."""
         return self.properties.get("Exists", None)
 
     @property
-    def welcome_page(self):
-        # type: () -> Optional[str]
+    def welcome_page(self) -> Optional[str]:
         """Specifies the server-relative URL for the list folder Welcome page."""
         return self.properties.get("WelcomePage", None)
 
+    @odata(name="UniqueContentTypeOrder")
     @property
-    def unique_content_type_order(self):
+    def unique_content_type_order(self) -> ContentTypeId:
         """Specifies the content type order for the list folder."""
         return self.properties.get("UniqueContentTypeOrder", ContentTypeId())
 
+    @odata(name="ContentTypeOrder")
     @property
-    def content_type_order(self):
+    def content_type_order(self) -> ContentTypeId:
         """Specifies the content type order for the list folder."""
         return self.properties.get("ContentTypeOrder", ContentTypeId())
 
+    @odata(name="TimeLastModified")
     @property
-    def time_last_modified(self):
-        # type: () -> Optional[datetime]
+    def time_last_modified(self) -> Optional[datetime]:
         """Gets the last time this folder or a direct child was modified in UTC."""
         return self.properties.get("TimeLastModified", datetime.min)
 
+    @odata(name="TimeCreated")
     @property
-    def time_created(self):
-        # type: () -> Optional[datetime]
+    def time_created(self) -> Optional[datetime]:
         """Gets when the folder was created in UTC."""
         return self.properties.get("TimeCreated", datetime.min)
 
     @property
-    def serverRelativeUrl(self):
-        # type: () -> Optional[str]
+    def server_relative_url(self) -> Optional[str]:
         """Gets the server-relative URL of the list folder."""
         return self.properties.get("ServerRelativeUrl", None)
 
+    @odata(name="ServerRelativePath")
     @property
-    def server_relative_path(self):
-        # type: () -> Optional[SPResPath]
+    def server_relative_path(self) -> Optional[SPResPath]:
         """Gets the server-relative Path of the list folder."""
         return self.properties.get("ServerRelativePath", SPResPath())
 
     @property
-    def property_ref_name(self):
-        # type: () -> Optional[str]
+    def property_ref_name(self) -> Optional[str]:  # type: ignore[override]
         return None
 
-    def get_property(self, name, default_value=None):
-        if default_value is None:
-            property_mapping = {
-                "ContentTypeOrder": self.content_type_order,
-                "UniqueContentTypeOrder": self.unique_content_type_order,
-                "ListItemAllFields": self.list_item_all_fields,
-                "ParentFolder": self.parent_folder,
-                "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)
-
     def set_property(self, name, value, persist_changes=True):
-        super(Folder, self).set_property(name, value, persist_changes)
-        # fallback: create a new resource path
+        super().set_property(name, value, persist_changes)
         if name == "UniqueId":
             self._resource_path = self.context.web.get_folder_by_id(value).resource_path
         if self._resource_path is None:
             if name == "ServerRelativeUrl":
-                self._resource_path = (
-                    self.context.web.get_folder_by_server_relative_url(
-                        value
-                    ).resource_path
-                )
+                self._resource_path = self.context.web.get_folder_by_server_relative_url(value).resource_path
             elif name == "ServerRelativePath":
-                self._resource_path = (
-                    self.context.web.get_folder_by_server_relative_path(
-                        value
-                    ).resource_path
-                )
+                self._resource_path = self.context.web.get_folder_by_server_relative_path(value).resource_path
         return self