Office365-REST-Python-Client 3.0.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

office365/sharepoint/folders/folder.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import IO, TYPE_CHECKING, Callable, List, Optional, Union
+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
@@ -25,15 +27,19 @@ from office365.sharepoint.sharing.object_sharing_information import ObjectSharin
 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.thresholds import SAFE_PAGE_SIZE, Limits, limit
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 from office365.sharepoint.utilities.move_copy_options import MoveCopyOptions
 from office365.sharepoint.utilities.move_copy_util import MoveCopyUtil
 
 if TYPE_CHECKING:
+    from office365.runtime.converters.dataframe import DataFrameResult
     from office365.sharepoint.files.collection import FileCollection
     from office365.sharepoint.files.file import File
     from office365.sharepoint.folders.collection import FolderCollection
 
+_DEFAULT_CHUNK_SIZE = Limits.UPLOAD_SESSION_CHUNK.value  # simple-upload threshold / upload-session chunk
+
 
 class Folder(Entity):
     """Represents a folder in a SharePoint Website."""
@@ -57,47 +63,158 @@ 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: IO, after_file_downloaded: Optional[Callable[[File], None]] = None, recursive: bool = 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 (typing.IO): A download zip file object
+            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.
+        """
+        return MoveCopyUtil.download_folder_as_zip(
+            self, download_file, after_file_downloaded, recursive, include_versions, progress
+        )
+
+    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).
         """
-        return MoveCopyUtil.download_folder(self, download_file, after_file_downloaded, recursive)
+        return MoveCopyUtil.upload_folder(self, source, after_file_uploaded, recursive, progress, chunk_size)
+
+    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.
+
+        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).
+
+        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).
+
+        Returns:
+            The target folder (chainable).
+        """
+        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) -> FolderCollection:
+    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.runtime.queries.deferred import DeferredOperationQuery
         from office365.sharepoint.folders.collection import FolderCollection
 
         return_type = FolderCollection(self.context, self.folders.resource_path, self)
 
         def _get_folders(parent: Folder) -> None:
-            [return_type.add_child(f) for f in parent.folders]
-            if recursive:
-                for folder in parent.folders:
-                    folder.ensure_properties(["Folders"]).after_execute(lambda _, f=folder: _get_folders(parent=f))
-
-        self.ensure_properties(["Folders"]).after_execute(lambda _: _get_folders(parent=self))
+            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
 
-    def get_files(self, recursive: bool = False) -> FileCollection:
-        """Retrieves files
+    @limit(Limits.LIST_VIEW, arg="page_size")
+    def get_files(
+        self,
+        recursive: bool = False,
+        progress: Optional[Callable[[Progress[File]], None]] = None,
+        page_size: int = SAFE_PAGE_SIZE,
+    ) -> FileCollection:
+        """Retrieves files (paged, so it works on folders with >5,000 items).
 
         Args:
             recursive (bool): Determines whether to enumerate folders recursively
+            progress: Optional hook invoked per scanned page with a
+              ``Progress[File]`` snapshot (``done`` = files discovered so far;
+              ``items`` = the files found in the page just scanned).
+            page_size (int): Items per page (kept below the 5,000-item list view
+              threshold so large folders are read without being throttled).
+
+        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
@@ -105,14 +222,38 @@ class Folder(Entity):
         return_type = FileCollection(self.context, resource_path, self)
 
         def _get_files(parent: Folder) -> None:
-            [return_type.add_child(f) for f in parent.files]
-            if recursive:
-                for folder in parent.folders:
-                    folder.ensure_properties(["Files", "Folders"]).after_execute(
-                        lambda _, f=folder: _get_files(parent=f)
-                    )
-
-        self.ensure_properties(["Files", "Folders"]).after_execute(lambda _: _get_files(parent=self))
+            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)
+            seen = {"count": 0}
+
+            def _on_files_page(col: FileCollection) -> None:
+                new_files = list(col)[seen["count"] :]
+                seen["count"] = len(col)
+                for file in new_files:
+                    return_type.add_child(file)
+                if callable(progress):
+                    progress(Progress(done=len(return_type), stage="scanning", items=new_files))
+                if recursive and not col.has_next:
+                    _scan_subfolders(parent)
+
+            files.get_all(page_size, page_loaded=_on_files_page)
+
+        def _scan_subfolders(parent: Folder) -> None:
+            subfolders = parent.folders
+            seen = {"count": 0}
+
+            def _on_folders_page(col: "FolderCollection") -> None:
+                for folder in list(col)[seen["count"] :]:
+                    _get_files(folder)
+                seen["count"] = len(col)
+
+            subfolders.get_all(page_size, page_loaded=_on_folders_page)
+
+        placeholder = DeferredOperationQuery(self.context)
+        self.context.add_query(placeholder).after_execute(lambda _: _get_files(self))
         return return_type
 
     def get_sharing_information(self) -> ObjectSharingInformation:
@@ -291,15 +432,76 @@ class Folder(Entity):
         self.context.add_query(qry)
         return self
 
-    def upload_file(self, file_name: str, content: Union[str, bytes]) -> File:
-        """Uploads a file into folder.
-        Note: This method only supports files up to 4MB in size!
+    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:
-            file_name (str): Specifies the URL of the file to be added
+            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 write_dataframe(
+        self,
+        relative_path: str,
+        df,
+        *,
+        format: str = "csv",  # noqa: A002
+        index: bool = False,
+        **opts,
+    ) -> File:
+        """Serialize a pandas DataFrame and write it as a file (CSV/XLSX/...).
+
+        The DataFrame counterpart of :meth:`upload_file` — it writes the frame's
+        **content**, not metadata. CSV is written UTF-8 with a BOM
+        (``utf-8-sig``) so Excel opens it with the columns intact;
+        ``format="xlsx"`` writes a worksheet (requires the ``[excel]`` extra).
+        The returned :class:`File` is deferred — the caller executes it.
+
+        Args:
+            relative_path: File name or path relative to this folder.
+            df: A pandas DataFrame.
+            format: ``"csv"`` (default), ``"xlsx"``/``"excel"``, ``"json"``, ...
+            index: Whether to write the DataFrame index (default False).
+            opts: Extra kwargs forwarded to the pandas writer.
+        """
+        from office365.runtime.converters.dataframe import dataframe_to_bytes
+
+        return self.upload_file(relative_path, dataframe_to_bytes(df, format, index, **opts))
+
+    def read_dataframe(self, relative_path: str, *, format: str = "csv", **opts) -> "DataFrameResult":  # noqa: A002
+        """Read a file in this folder's **content** into a DataFrame (deferred result).
+
+        Parses the file content (CSV/XLSX/JSON/Parquet) — not metadata. Run with
+        ``execute_query()`` and read ``.value``:
+
+            >>> df = folder.read_dataframe("stocks.csv").execute_query().value
+        """
+        url = f"{self.server_relative_url}/{relative_path}".replace("//", "/")
+        file = self.context.web.get_file_by_server_relative_url(url)
+        return file.read_dataframe(format=format, **opts)
 
     def update_document_sharing_info(
         self,
@@ -446,7 +648,12 @@ class Folder(Entity):
 
     @property
     def files(self) -> FileCollection:
-        """Specifies the collection of files contained in the list folder."""
+        """Specifies the collection of files contained in the list folder.
+
+        A single-shot load (``ctx.load(folder, ["Files"])`` / ``.get()``) is trimmed
+        at the 5,000-item list view threshold; use :meth:`get_files` (paged) for
+        folders that may exceed it.
+        """
         from office365.sharepoint.files.collection import FileCollection
 
         return self.properties.get(
@@ -455,13 +662,48 @@ class Folder(Entity):
 
     @property
     def folders(self) -> FolderCollection:
-        """Specifies the collection of list folders contained within the list folder."""
+        """Specifies the collection of list folders contained within the list folder.
+
+        A single-shot load (``ctx.load(folder, ["Folders"])`` / ``.get()``) is
+        trimmed at the 5,000-item list view threshold; use ``folders.get_all(
+        page_size=2000)`` for folders that may exceed it.
+        """
         from office365.sharepoint.folders.collection import FolderCollection
 
         return self.properties.get(
             "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]) -> list[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.
+
+        Args:
+            relative_paths (Iterable[str]): Paths relative to this folder.
+
+        Returns:
+            list[Folder]: The ensured folders.
+        """
+        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)]
+        return [self.ensure_folder(path) for path in deepest]
+
     @odata(name="ParentFolder")
     @property
     def parent_folder(self) -> Folder:

office365/sharepoint/htmlpages/html_page.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from office365.sharepoint.entity import Entity
+
+
+class HtmlPage(Entity):
+    @property
+    def id_(self) -> Optional[int]:
+        """Gets the Id property"""
+        return self.properties.get("Id", None)
+
+    @property
+    def entity_type_name(self) -> str:
+        return "SP.HtmlPages.HtmlPage"

office365/sharepoint/htmlpages/html_page_service.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from office365.runtime.paths.resource_path import ResourcePath
+from office365.sharepoint.entity import Entity
+from office365.sharepoint.entity_collection import EntityCollection
+from office365.sharepoint.htmlpages.html_page import HtmlPage
+
+
+class HtmlPageService(Entity):
+    @property
+    def pages(self) -> EntityCollection[HtmlPage]:
+        """Gets the Pages property"""
+        return self.properties.get(
+            "Pages", EntityCollection[HtmlPage](self.context, HtmlPage, ResourcePath("Pages", self.resource_path))
+        )
+
+    @property
+    def entity_type_name(self) -> str:
+        return "SP.HtmlPages.HtmlPageService"

office365/sharepoint/internal/image_content_part.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
+from dataclasses import field
+
 from office365.runtime.client_value import ClientValue
+from office365.sharepoint.internal.image_url import ImageUrl
 
 
 class ImageContentPart(ClientValue):
+    ImageUrl: ImageUrl = field(default_factory=ImageUrl)
+
     @property
     def entity_type_name(self) -> str:
         return "Microsoft.SharePoint.Internal.ImageContentPart"

office365/sharepoint/internal/paths/web.py

@@ -1,5 +1,7 @@
+from urllib.parse import urlparse
+
+from office365.runtime.http.url import is_absolute_url
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.utilities import is_absolute_url, urlparse
 
 
 class WebPath(ResourcePath):

office365/sharepoint/internal/sticky_routing_options.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from office365.runtime.client_value import ClientValue
+
+
+class StickyRoutingOptions(ClientValue):
+    InteractionId: str | None = None
+    SessionId: str | None = None
+    SessionTicket: str | None = None
+
+    @property
+    def entity_type_name(self) -> str:
+        return "Microsoft.SharePoint.Internal.StickyRoutingOptions"

office365/sharepoint/ir/migration.py

@@ -1,3 +1,6 @@
+from typing_extensions import Self
+
+from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity import Entity
 
 
@@ -7,3 +10,9 @@ class IRMigration(Entity):
     @property
     def entity_type_name(self) -> str:
         return "Microsoft.SharePoint.IR.IRMigration"
+
+    def delete_and_recreate_ir_list(self) -> Self:
+        """DeleteAndRecreateIRList operation."""
+        qry = ServiceOperationQuery(self, "DeleteAndRecreateIRList", None, {}, None, None)
+        self.context.add_query(qry)
+        return self

office365/sharepoint/likes/liked_by_information.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from office365.runtime.paths.resource_path import ResourcePath
+from office365.runtime.types.odata_property import odata
 from office365.sharepoint.entity import Entity
 from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.likes.user_entity import UserEntity
@@ -19,6 +20,7 @@ class LikedByInformation(Entity):
         """MUST be TRUE if the current user has liked the list item."""
         return self.properties.get("isLikedByUser", None)
 
+    @odata(name="likedBy")
     @property
     def liked_by(self) -> EntityCollection[UserEntity]:
         """
@@ -29,12 +31,6 @@ class LikedByInformation(Entity):
             "likedBy", EntityCollection(self.context, UserEntity, ResourcePath("likedBy", self.resource_path))
         )
 
-    def get_property(self, name, default_value=None):
-        if default_value is None:
-            property_mapping = {"likedBy": self.liked_by}
-            default_value = property_mapping.get(name, None)
-        return super().get_property(name, default_value)
-
     @property
     def entity_type_name(self):
         return "Microsoft.SharePoint.Likes.LikedByInformation"

office365/sharepoint/listitems/caml/__init__.py

@@ -0,0 +1,31 @@
+"""Typed CAML query builder.
+
+Build CAML ``ViewXml`` from composable Python objects instead of raw strings::
+
+    from office365.sharepoint.listitems.caml import Caml, CamlQuery
+
+    query = (
+        CamlQuery.builder()
+        .where(Caml.text("Status").eq("Active"))
+        .order_by("Created", ascending=False)
+        .row_limit(2000)
+        .build()
+    )
+"""
+
+from office365.sharepoint.listitems.caml.builder import QueryBuilder
+from office365.sharepoint.listitems.caml.expressions import Caml, CamlExpr, Field
+from office365.sharepoint.listitems.caml.fields import FieldRef
+from office365.sharepoint.listitems.caml.query import CamlQuery
+from office365.sharepoint.listitems.caml.values import Value, ValueType
+
+__all__ = [
+    "Caml",
+    "CamlExpr",
+    "CamlQuery",
+    "Field",
+    "FieldRef",
+    "QueryBuilder",
+    "Value",
+    "ValueType",
+]