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

office365/sharepoint/folders/folder.py

@@ -27,16 +27,18 @@ 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 = 4 * 1024 * 1024  # simple-upload threshold / upload-session chunk
+_DEFAULT_CHUNK_SIZE = Limits.UPLOAD_SESSION_CHUNK.value  # simple-upload threshold / upload-session chunk
 
 
 class Folder(Entity):
@@ -192,18 +194,22 @@ class Folder(Entity):
         self.context.add_query(placeholder).after_execute(lambda _: _get_folders(self))
         return return_type
 
+    @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
+        """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 folder with a
+            progress: Optional hook invoked per scanned page with a
               ``Progress[File]`` snapshot (``done`` = files discovered so far;
-              ``items`` = the files found in the folder just scanned).
+              ``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.
@@ -216,21 +222,35 @@ class Folder(Entity):
         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)
+            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))
@@ -443,6 +463,46 @@ class Folder(Entity):
             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,
         user_role_assignments: List[UserRoleAssignment],
@@ -588,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(
@@ -597,7 +662,12 @@ 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(
@@ -616,23 +686,23 @@ class Folder(Entity):
         """
         return self.folders.ensure_by_path(relative_path)
 
-    def ensure_folders(self, relative_paths: Iterable[str]) -> Folder:
+    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.
-        Returns ``self`` for chaining.
 
         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)]
-        for path in deepest:
-            self.ensure_folder(path)
-        return self
+        return [self.ensure_folder(path) for path in deepest]
 
     @odata(name="ParentFolder")
     @property

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/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/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",
+]

office365/sharepoint/listitems/caml/builder.py

@@ -0,0 +1,129 @@
+"""Fluent builder for the CAML ``<View>`` document.
+
+Assembles ``ViewFields``/``Where``/``GroupBy``/``OrderBy``/``RowLimit``/``Scope``
+into a ``ViewXml`` string (or a :class:`CamlQuery`):
+
+    from office365.sharepoint.listitems.caml import Caml, CamlQuery
+    from office365.sharepoint.views.scope import ViewScope
+
+    query = (CamlQuery.builder()
+        .where(Caml.text("Status").eq("Active"))
+        .order_by("Created", ascending=False)
+        .row_limit(2000)
+        .scope(ViewScope.RecursiveAll)
+        .build())
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+from xml.sax.saxutils import quoteattr
+
+from typing_extensions import Self
+
+from office365.sharepoint.listitems.caml.expressions import And, CamlExpr, _as_field_ref, _fold
+from office365.sharepoint.listitems.caml.fields import FieldRef
+from office365.sharepoint.views.scope import ViewScope
+
+if TYPE_CHECKING:
+    from office365.sharepoint.listitems.caml.query import CamlQuery
+
+
+class QueryBuilder:
+    """Fluent builder that renders the CAML ``<View>`` element."""
+
+    def __init__(self) -> None:
+        self._where: Optional[CamlExpr] = None
+        self._order_by: list[FieldRef] = []
+        self._group_by: list[FieldRef] = []
+        self._view_fields: list[FieldRef] = []
+        self._row_limit: Optional[int] = None
+        self._paged = True
+        self._scope: ViewScope = ViewScope.DefaultValue
+
+    def where(self, *conditions: CamlExpr) -> Self:
+        """Set the ``<Where>`` filter (multiple conditions are combined with ``<And>``)."""
+        if conditions:
+            self._where = _fold(And, conditions)
+        return self
+
+    def order_by(self, *fields: Any, ascending: bool = True) -> Self:
+        """Add one or more ``<OrderBy>`` fields (call again to append)."""
+        for field in fields:
+            ref = _as_field_ref(field)
+            self._order_by.append(ref if ref.ascending is not None else ref._copy(ascending=ascending))
+        return self
+
+    def group_by(self, field: Any, *, collapse: bool = True) -> Self:
+        """Add a ``<GroupBy>`` field."""
+        ref = _as_field_ref(field)
+        self._group_by.append(ref if ref.collapse is not None else ref._copy(collapse=collapse))
+        return self
+
+    def view_fields(self, *names: Any) -> Self:
+        """Add ``<ViewFields>`` entries (a ``str``, ``Field`` or ``FieldRef``)."""
+        self._view_fields.extend(_as_field_ref(name) for name in names)
+        return self
+
+    def row_limit(self, top: int, *, paged: bool = True) -> Self:
+        """Set ``<RowLimit>`` (``Paged="TRUE"`` by default)."""
+        self._row_limit = top
+        self._paged = paged
+        return self
+
+    def scope(self, scope: ViewScope) -> Self:
+        """Set the ``Scope`` attribute of ``<View>``."""
+        self._scope = scope
+        return self
+
+    @property
+    def is_paged(self) -> bool:
+        """Whether the query enables server-driven paging (``RowLimit Paged="TRUE"``)."""
+        return self._row_limit is not None and self._paged
+
+    @property
+    def field_refs(self) -> set[str]:
+        """Fields the query filters or sorts on (``ViewFields`` are excluded)."""
+        names: set[str] = set()
+        if self._where is not None:
+            names |= self._where.field_refs
+        for ref in (*self._order_by, *self._group_by):
+            names.add(ref.name)
+        return names
+
+    def to_xml(self) -> str:
+        """Render the CAML ``<View>`` document."""
+        scope = self._scope.value if isinstance(self._scope, ViewScope) else str(self._scope)
+        parts = [f"<View Scope={quoteattr(scope)}>"]
+        if self._view_fields:
+            parts.append("<ViewFields>" + "".join(ref.to_xml() for ref in self._view_fields) + "</ViewFields>")
+        query = self._query_xml()
+        if query:
+            parts.append(query)
+        if self._row_limit is not None:
+            paged = ' Paged="TRUE"' if self._paged else ""
+            parts.append(f"<RowLimit{paged}>{self._row_limit}</RowLimit>")
+        parts.append("</View>")
+        return "".join(parts)
+
+    def _query_xml(self) -> str:
+        query: list[str] = []
+        if self._where is not None:
+            query.append(f"<Where>{self._where.to_xml()}</Where>")
+        if self._group_by:
+            query.append("<GroupBy>" + "".join(ref.to_xml() for ref in self._group_by) + "</GroupBy>")
+        if self._order_by:
+            query.append("<OrderBy>" + "".join(ref.to_xml() for ref in self._order_by) + "</OrderBy>")
+        return "<Query>" + "".join(query) + "</Query>" if query else ""
+
+    def build(self) -> "CamlQuery":
+        """Build a :class:`CamlQuery` (raw ``ViewXml`` + the expression AST)."""
+        from office365.sharepoint.listitems.caml.query import CamlQuery
+
+        query = CamlQuery()
+        query.ViewXml = self.to_xml()
+        query._expr = self
+        return query
+
+    def __repr__(self) -> str:
+        return self.to_xml()