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

office365/sharepoint/files/collection.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import hashlib
+import io
 import os
+import tempfile
 import uuid
 from typing import IO, TYPE_CHECKING, Any, Callable, Optional, Union, cast
 
-from office365.runtime.client_result import ClientResult
+from office365.runtime.operations import Progress, ProgressCallback
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
@@ -15,15 +17,40 @@ from office365.sharepoint.files.creation_information import FileCreationInformat
 from office365.sharepoint.files.file import File
 from office365.sharepoint.files.publish.status import FileStatus
 from office365.sharepoint.pages.template_file_type import TemplateFileType
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD, Limits, ensure_within, limit
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 if TYPE_CHECKING:
     from office365.sharepoint.folders.folder import Folder
 
+_DEFAULT_CHUNK_SIZE = Limits.UPLOAD_SESSION_CHUNK.value  # simple-upload threshold / upload-session chunk
+
+
+def _stream_size(stream: IO) -> int:
+    """Byte length of a seekable stream (file or ``io.BytesIO``), preserving position.
+
+    Raises:
+        ValueError: When the upload source is not seekable.
+    """
+    pos = stream.tell()
+    try:
+        stream.seek(0, io.SEEK_END)
+        return stream.tell()
+    except OSError as e:
+        raise ValueError("Upload source must be a seekable file or stream") from e
+    finally:
+        try:
+            stream.seek(pos)
+        except OSError:
+            pass
+
 
 class FileCollection(EntityCollection[File]):
     """Represents a collection of File resources."""
 
+    _list_view_threshold = LIST_VIEW_THRESHOLD
+    _truncation_hint = "page it with Folder.get_files(page_size=2000) or files.get_all(page_size=2000)"
+
     def __init__(
         self,
         context: ClientContext,
@@ -59,6 +86,44 @@ class FileCollection(EntityCollection[File]):
             content = path_or_file.read()
             return self.add(name, content, True)
 
+    @limit(Limits.FILE_UPLOAD)
+    def upload_content(
+        self,
+        content: bytes,
+        file_name: str,
+        chunk_size: int = _DEFAULT_CHUNK_SIZE,
+        progress: Optional[ProgressCallback] = None,
+    ) -> File:
+        """Uploads in-memory content, dispatching by size.
+
+        Files at or below ``chunk_size`` use the simple :meth:`upload`; larger
+        ones use a resumable :meth:`create_upload_session` (staged to a temp
+        file). The returned :class:`File` is deferred — the caller executes it.
+
+        Args:
+            content (bytes): File content to upload.
+            file_name (str): New file name.
+            chunk_size (int): Upload-session chunk size / size threshold (bytes).
+            progress: Optional hook invoked with a ``Progress`` snapshot
+              (``done``/``total`` in bytes; per chunk for session uploads, once
+              after the upload completes for the simple path).
+        """
+        ensure_within(Limits.FILE_UPLOAD, len(content), context=f"file '{file_name}'")
+        if len(content) <= chunk_size:
+            file = self.upload(io.BytesIO(content), file_name)
+            if callable(progress):
+                size = len(content)
+
+                def _uploaded(_: Any) -> None:
+                    progress(Progress(done=size, total=size, stage="uploading"))
+
+                file.after_execute(_uploaded)
+            return file
+        with tempfile.NamedTemporaryFile(suffix=file_name) as tmp:
+            tmp.write(content)
+            tmp.flush()
+            return self.create_upload_session(tmp.name, chunk_size=chunk_size, file_name=file_name, progress=progress)
+
     def upload_with_checksum(self, file_object: IO, chunk_size: int = 1024) -> File:
         """ """
         h = hashlib.md5()
@@ -78,6 +143,7 @@ class FileCollection(EntityCollection[File]):
         file_or_path: IO | str,
         chunk_size: int,
         chunk_uploaded: Optional[Callable[[int, Any], None]] = None,
+        progress: Optional[ProgressCallback] = None,
         file_name: Optional[str] = None,
         **kwargs: Any,
     ) -> File:
@@ -88,6 +154,8 @@ class FileCollection(EntityCollection[File]):
             file_or_path: File object or path to upload
             chunk_size: Size of upload chunks in bytes
             chunk_uploaded: Callback that accepts offset and optional additional args
+            progress: Optional hook invoked per uploaded chunk with a
+              ``Progress`` snapshot (``done`` = bytes uploaded, ``total`` = file size).
             file_name: Optional name for the uploaded file
             **kwargs: Additional arguments passed to the upload implementation
         """
@@ -99,17 +167,20 @@ class FileCollection(EntityCollection[File]):
         else:
             f = file_or_path
 
-        file_size = os.fstat(f.fileno()).st_size
-        file_name = file_name if file_name else os.path.basename(f.name)
+        file_size = _stream_size(f)
+        if file_name is None:
+            stream_name = getattr(f, "name", None)
+            file_name = os.path.basename(stream_name) if stream_name else None
+        if not file_name:
+            raise ValueError("file_name is required when uploading from an unnamed stream")
         upload_id = str(uuid.uuid4())
 
         def _upload(return_type: File) -> None:
-            def _after_uploaded(result: ClientResult) -> None:
-                _upload(return_type)
-
             uploaded_bytes = f.tell()
             if callable(chunk_uploaded):
                 chunk_uploaded(uploaded_bytes, **kwargs)  # type: ignore[call-arg]
+            if callable(progress):
+                progress(Progress(done=uploaded_bytes, total=file_size, stage="uploading"))
 
             content = f.read(chunk_size)
             if uploaded_bytes == file_size:
@@ -118,9 +189,11 @@ class FileCollection(EntityCollection[File]):
                 return
 
             if uploaded_bytes == 0:
-                return_type.start_upload(upload_id, content).after_execute(_after_uploaded)
+                return_type.start_upload(upload_id, content).after_execute(lambda _: _upload(return_type))
             elif uploaded_bytes + len(content) < file_size:
-                return_type.continue_upload(upload_id, uploaded_bytes, content).after_execute(_after_uploaded)
+                return_type.continue_upload(upload_id, uploaded_bytes, content).after_execute(
+                    lambda _: _upload(return_type)
+                )
             else:
                 return_type.finish_upload(upload_id, uploaded_bytes, content).after_execute(_upload)
 

office365/sharepoint/files/file.py

@@ -13,6 +13,7 @@ from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.client_result import ClientResult
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.operations import Progress
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.function import FunctionQuery
@@ -48,6 +49,7 @@ from office365.sharepoint.webparts.limited_manager import LimitedWebPartManager
 from office365.sharepoint.webparts.personalization_scope import PersonalizationScope
 
 if TYPE_CHECKING:
+    from office365.runtime.converters.dataframe import DataFrameResult
     from office365.sharepoint.client_context import ClientContext
 
 
@@ -140,10 +142,41 @@ class File(AbstractFile):
     def get_content(self) -> ClientResult[bytes]:
         """Downloads a file content"""
         return_type = ClientResult(self.context, bytes())
-        qry = FunctionQuery(self, "$value", return_type=return_type)
+        qry = FunctionQuery(self, "$value", return_type=return_type, return_raw_content=True)
         self.context.add_query(qry)
         return return_type
 
+    def read_dataframe(self, *, format: str = "csv", **opts) -> "DataFrameResult":  # noqa: A002
+        """Read this file's **content** into a pandas DataFrame (deferred result).
+
+        Parses the file content (CSV/XLSX/JSON/Parquet) — it does **not** export
+        the file's metadata; those are plain properties (``file.name``,
+        ``file.length``, ``file.time_last_modified``, ...). Run with
+        ``execute_query()`` and read ``.value``:
+
+            >>> df = file.read_dataframe().execute_query().value
+        """
+        from office365.runtime.converters.dataframe import DataFrameResult, dataframe_from_bytes
+
+        result = DataFrameResult(self.context)
+
+        def _convert(return_type: ClientResult[bytes]) -> None:
+            result.set_property("__value", dataframe_from_bytes(return_type.value, format, **opts))
+
+        self.get_content().after_execute(_convert)
+        return result
+
+    def write_dataframe(self, df, *, format: str = "csv", index: bool = False, **opts) -> Self:  # noqa: A002
+        """Write a pandas DataFrame to this file's **content** (deferred).
+
+        Serializes the frame (CSV is UTF-8 with a BOM) and queues a
+        ``SaveBinaryStream``; run with ``execute_query()``. This replaces the
+        file content, not its metadata.
+        """
+        from office365.runtime.converters.dataframe import dataframe_to_bytes
+
+        return self.save_binary_stream(dataframe_to_bytes(df, format, index, **opts))
+
     def get_exists(self) -> ClientResult[bool]:
         result = ClientResult(self.context, bool())
         result.set_property("__value", False)
@@ -271,6 +304,22 @@ class File(AbstractFile):
         self.context.add_query(qry)
         return return_type
 
+    def delete_object(self, bypass_shared_lock: bool = False) -> Self:
+        """Deletes the file.
+
+        Args:
+            bypass_shared_lock: Send ``Prefer: bypass-shared-lock`` so the delete
+                succeeds even when the file is open for editing. Without it the
+                server rejects the request with
+                :class:`~office365.runtime.exceptions.FileLockedException` (HTTP 423).
+        """
+        super().delete_object()
+        if bypass_shared_lock:
+            from office365.runtime.http.prefer import prefer_bypass_shared_lock
+
+            self.context.before_execute(prefer_bypass_shared_lock, once=True)
+        return self
+
     def recycle(self) -> ClientResult[str]:
         """Moves the file to the Recycle Bin and returns the identifier of the new Recycle Bin item."""
         return_type = ClientResult(self.context, str())
@@ -435,6 +484,50 @@ class File(AbstractFile):
         self.ensure_properties(["ServerRelativePath", "Name"]).after_execute(lambda _: _source_file_resolved())
         return self
 
+    def move_by_path(
+        self,
+        destination: Union[str, Folder],
+        flag: MoveOperations = MoveOperations.overwrite,
+    ) -> Self:
+        """Moves the file to the specified destination using ``MoveCopyUtil.MoveFileByPath``.
+
+        Unlike :meth:`move_to_using_path` (``File/MoveToUsingPath``), both paths
+        travel in the request body, so deep folder structures don't hit
+        SharePoint's URL length limit.
+
+        Args:
+            destination (str or office365.sharepoint.folders.folder.Folder): Specifies the
+                destination folder path or an existing folder object.
+            flag (MoveOperations): Specifies the kind of move operation
+                (defaults to ``overwrite``).
+        """
+        from office365.sharepoint.utilities.move_copy_options import MoveCopyOptions
+        from office365.sharepoint.utilities.move_copy_util import MoveCopyUtil
+
+        def _move_by_path(destination_folder: Folder) -> None:
+            assert self.name is not None
+            assert self.server_relative_path is not None
+            file_path = "/".join([str(destination_folder.server_relative_path), self.name])
+            options = MoveCopyOptions(KeepBoth=flag != MoveOperations.overwrite)
+            MoveCopyUtil.move_file_by_path(self.context, str(self.server_relative_path), file_path, options)
+
+            def _update_file(_) -> None:
+                self.set_property("ServerRelativePath", file_path)
+
+            self.context.after_execute(_update_file)
+
+        def _source_file_resolved() -> None:
+            if isinstance(destination, Folder):
+                dest = destination
+                destination.ensure_property("ServerRelativePath").after_execute(lambda _: _move_by_path(dest))
+            else:
+                self.context.web.ensure_folder_path(destination).get().select(["ServerRelativePath"]).after_execute(
+                    _move_by_path
+                )
+
+        self.ensure_properties(["ServerRelativePath", "Name"]).after_execute(lambda _: _source_file_resolved())
+        return self
+
     def publish(self, comment: str) -> Self:
         """Submits the file for content approval with the specified comment.
 
@@ -635,14 +728,15 @@ class File(AbstractFile):
     def save_binary(context: ClientContext, server_relative_url: str, content: bytes):
         """Uploads a file"""
         try:
-            decoded_server_relative_url = unquote(server_relative_url)
+            decoded = unquote(server_relative_url)
         except (ValueError, AttributeError, TypeError):
-            decoded_server_relative_url = server_relative_url
+            decoded = server_relative_url
+        # OData literals escape embedded single quotes by doubling them (' -> '')
+        decoded_server_relative_url = decoded.replace("'", "''")
 
-        url = quote(
-            rf"{context.service_root_url}/web/getFileByServerRelativePath"
-            rf"(DecodedUrl='{decoded_server_relative_url}')/\$value",
-            safe=":/",
+        url = (
+            f"{context.service_root_url}/web/getFileByServerRelativePath"
+            f"(DecodedUrl='{quote(decoded_server_relative_url)}')/$value"
         )
 
         request = RequestOptions(url)
@@ -658,14 +752,15 @@ class File(AbstractFile):
         Returns the file object located at the specified server-relative URL.
         """
         try:
-            decoded_server_relative_url = unquote(server_relative_url)
+            decoded = unquote(server_relative_url)
         except (ValueError, AttributeError, TypeError):
-            decoded_server_relative_url = server_relative_url
+            decoded = server_relative_url
+        # OData literals escape embedded single quotes by doubling them (' -> '')
+        decoded_server_relative_url = decoded.replace("'", "''")
 
-        url = quote(
-            rf"{context.service_root_url}/web/getFileByServerRelativePath("
-            rf"DecodedUrl='{decoded_server_relative_url}')/\$value",
-            safe=":/",
+        url = (
+            f"{context.service_root_url}/web/getFileByServerRelativePath"
+            f"(DecodedUrl='{quote(decoded_server_relative_url)}')/$value"
         )
 
         request = RequestOptions(url)
@@ -692,7 +787,14 @@ class File(AbstractFile):
         self.ensure_property("ServerRelativePath").after_execute(lambda _: _download_inner())
         return self
 
-    def download_session(self, file_object, chunk_downloaded=None, chunk_size=1024 * 1024, use_path=True):
+    def download_session(
+        self,
+        file_object,
+        chunk_downloaded=None,
+        chunk_size=1024 * 1024,
+        use_path=True,
+        progress=None,
+    ):
         """Download a file content. Use this method to download a content of a large size
 
         Args:
@@ -700,6 +802,9 @@ class File(AbstractFile):
             chunk_downloaded ((int)->None or None):
             chunk_size (int):
             use_path (bool): File addressing by path flag
+            progress (office365.runtime.operations.ProgressCallback): Optional hook
+              invoked per chunk with a ``Progress`` snapshot (``done`` = bytes
+              downloaded so far, ``total`` = content length when known).
         """
 
         def _download_as_stream():
@@ -714,11 +819,14 @@ class File(AbstractFile):
 
             def _process_response(response: requests.Response) -> None:
                 self.context.pending_request().beforeExecute -= _construct_request
+                total = int(response.headers.get("Content-Length", 0)) or None
                 bytes_read = 0
                 for chunk in response.iter_content(chunk_size=chunk_size):
                     bytes_read += len(chunk)
                     if callable(chunk_downloaded):
                         chunk_downloaded(bytes_read)
+                    if callable(progress):
+                        progress(Progress(done=bytes_read, total=total, stage="downloading"))
                     file_object.write(chunk)
 
             self.context.add_query(qry).before_execute(_construct_request, once=False).after_execute(

office365/sharepoint/files/file_url_virus_status_update.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from office365.sharepoint.entity import Entity
+
+
+class FileUrlVirusStatusUpdate(Entity):
+    @property
+    def file_url(self) -> Optional[str]:
+        """Gets the fileUrl property"""
+        return self.properties.get("fileUrl", None)
+
+    @property
+    def virus_message(self) -> Optional[str]:
+        """Gets the virusMessage property"""
+        return self.properties.get("virusMessage", None)
+
+    @property
+    def virus_status(self) -> bytes | None:
+        """Gets the virusStatus property"""
+        return self.properties.get("virusStatus", None)

office365/sharepoint/files/versionbatchdeleteparameters.py

@@ -20,3 +20,4 @@ class FileVersionBatchDeleteParameters(ClientValue):
     MajorVersionLimit: int | None = None
     MajorWithMinorVersionsLimit: int | None = None
     SyncListPolicy: bool | None = None
+    BypassSiteLock: bool | None = None

office365/sharepoint/files/versions/version.py

@@ -5,8 +5,8 @@ from typing_extensions import Self
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.paths.v3.entity import EntityPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
+from office365.runtime.types.odata_property import odata
 from office365.sharepoint.entity import Entity
 
 
@@ -50,15 +50,13 @@ class FileVersion(Entity):
         """Specifies the creation date and time for the file version."""
         return self.properties.get("Created", datetime.min)
 
+    @odata(name="CreatedBy")
     @property
     def created_by(self):
         """Gets the user that created the file version."""
         from office365.sharepoint.principal.users.user import User
 
-        return self.properties.get(
-            "CreatedBy",
-            User(self.context, ResourcePath("CreatedBy", self.resource_path)),
-        )
+        return self.properties.get("CreatedBy", User(self.context, ResourcePath("CreatedBy", self.resource_path)))
 
     @property
     def id(self) -> Optional[int]:
@@ -85,20 +83,41 @@ class FileVersion(Entity):
         """Gets a value that specifies the check-in comment."""
         return self.properties.get("CheckInComment", None)
 
-    def get_property(self, name, default_value=None):
-        if default_value is None:
-            property_mapping = {
-                "CreatedBy": self.created_by,
-            }
-            default_value = property_mapping.get(name, None)
-        return super().get_property(name, default_value)
-
-    def set_property(self, key, value, persist_changes=True):  # type: ignore[override]
-        super().set_property(key, value, persist_changes)
-        if key.lower() == self.property_ref_name.lower():
-            assert self.parent_collection is not None
-            if self._resource_path is None:
-                self._resource_path = EntityPath(value, self.parent_collection.resource_path)
-            else:
-                self._resource_path.set_segment(value)
+    @property
+    def check_in_comment(self) -> Optional[str]:
+        """Gets the CheckInComment property"""
+        return self.properties.get("CheckInComment", None)
+
+    @property
+    def expiration_date(self) -> Optional[str]:
+        """Gets the ExpirationDate property"""
+        return self.properties.get("ExpirationDate", None)
+
+    @property
+    def length(self) -> Optional[int]:
+        """Gets the Length property"""
+        return self.properties.get("Length", None)
+
+    @property
+    def size(self) -> Optional[int]:
+        """Gets the Size property"""
+        return self.properties.get("Size", None)
+
+    @property
+    def snapshot_date(self) -> Optional[str]:
+        """Gets the SnapshotDate property"""
+        return self.properties.get("SnapshotDate", None)
+
+    @property
+    def property_ref_name(self) -> str:
+        return "ID"
+
+    def set_expiration_date(self, expiration_date: datetime) -> Self:
+        """SetExpirationDate operation.
+
+        Args:
+            expiration_date (datetime): expirationDate parameter
+        """
+        qry = ServiceOperationQuery(self, "SetExpirationDate", None, {"expirationDate": expiration_date}, None, None)
+        self.context.add_query(qry)
         return self

office365/sharepoint/folders/collection.py

@@ -10,12 +10,16 @@ from office365.sharepoint.folders.coloring_information import (
 )
 from office365.sharepoint.folders.colors import FolderColors
 from office365.sharepoint.folders.folder import Folder
+from office365.sharepoint.thresholds import LIST_VIEW_THRESHOLD
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 
 class FolderCollection(EntityCollection[Folder]):
     """Represents a collection of Folder resources."""
 
+    _list_view_threshold = LIST_VIEW_THRESHOLD
+    _truncation_hint = "page it with folders.get_all(page_size=2000)"
+
     def __init__(self, context, resource_path=None, parent=None):
         super().__init__(context, Folder, resource_path, parent)
 
@@ -32,8 +36,11 @@ class FolderCollection(EntityCollection[Folder]):
         self.context.add_query(qry)
         return return_type
 
-    def ensure_path(self, path: str) -> Folder:
-        """Ensures a folder exist
+    def ensure_by_path(self, path: str) -> Folder:
+        """Ensure a folder tree exists at the given path.
+
+        Creates any missing intermediate folders along a server- or site-relative
+        path (e.g. ``"Shared Documents/Projects/2026"``).
 
         Args:
             path (str): server or site relative url to a folder