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

office365/migration/sharepoint/tenant_assessor.py

@@ -18,14 +18,16 @@ from collections.abc import Callable
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from office365.migration._util import coerce_int, emit_progress
 from office365.migration.assessment.containers import ScanContainer
 from office365.migration.assessment.report import AssessmentReport
 from office365.migration.assessment.runner import ScanRunner
 from office365.migration.assessment.scanners import AssessmentOptions
+from office365.migration.sharepoint.options import SharePointAssessmentOptions
 from office365.migration.sharepoint.registry import sharepoint_scan_pairs
 from office365.migration.sharepoint.scanners.summary import SiteScanSummary
 from office365.runtime.client_result import ClientResult
+from office365.runtime.converters.scalars import parse_int
+from office365.runtime.operations import emit_progress
 from office365.sharepoint.entity import Entity
 
 if TYPE_CHECKING:
@@ -48,7 +50,7 @@ class MigrationTenantAssessor(Entity):
     def __init__(self, tenant: "Tenant", options: AssessmentOptions | None = None) -> None:
         super().__init__(tenant.context)
         self._tenant = tenant
-        self._options = options or AssessmentOptions()
+        self._options = options or SharePointAssessmentOptions()
 
     def assess(
         self,
@@ -77,7 +79,7 @@ class MigrationTenantAssessor(Entity):
                     site_url=site.url,
                     owner=site.owner_login_name,
                     storage_bytes=int(storage) if storage is not None else None,
-                    web_count=coerce_int(site.webs_count) or 0,
+                    web_count=parse_int(site.webs_count) or 0,
                     last_modified=_clean_modified(site.last_content_modified_date),
                     lock_state=site.lock_state,
                     report_impacted_only=True,

office365/migration/sharepoint/transfer.py

@@ -21,11 +21,12 @@ from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING, Tuple
 
 from office365.runtime.parallel import run_parallel
+from office365.sharepoint.thresholds import Limits
 
 if TYPE_CHECKING:
     from office365.sharepoint.folders.folder import Folder
 
-_DEFAULT_CHUNK_SIZE = 4 * 1024 * 1024
+_DEFAULT_CHUNK_SIZE = Limits.UPLOAD_SESSION_CHUNK.value
 
 # runtime-evaluated alias (typing form: the ``|``/``tuple[...]`` operators need 3.9+)
 Failure = Tuple[str, str]  # (dest_path, error)
@@ -68,7 +69,8 @@ def _transfer_files_parallel(
 
     parents = {dest.rsplit("/", 1)[0] for dest, _ in files if "/" in dest}
     if parents:
-        target_folder.ensure_folders(parents).execute_query()
+        target_folder.ensure_folders(parents)
+        target_folder.execute_query()
 
     failures: list[Failure] = []
     context_factory = context_factory or (lambda: target_folder.context.clone(target_folder.context.base_url))

office365/migration/tasks.py

@@ -0,0 +1,121 @@
+"""Migration tasks — declarative source → target descriptors (SPMT ``Add-SPMTTask``).
+
+Mirrors ``Microsoft.SharePoint.MigrationTool.PowerShell``'s task types:
+**FileShare** (a local folder), **SharePoint** (a source site — all lists, or
+selected ones), and **Json**-defined tasks (the ``-JsonDefinition`` format).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+__all__ = ["FILE_SHARE", "SHAREPOINT", "MigrationTask"]
+
+FILE_SHARE = "FileShare"
+SHAREPOINT = "SharePoint"
+
+
+@dataclass
+class MigrationTask:
+    """A declarative migration task (source → target mapping)."""
+
+    kind: str = FILE_SHARE
+    file_share_source: str | None = None
+    sharepoint_source_site_url: str | None = None
+    source_list: str | None = None
+    source_list_relative_path: str | None = None
+    target_site_url: str | None = None
+    target_list: str | None = None
+    target_list_relative_path: str | None = None
+    migrate_all: bool = False
+    migration_type: str = "Content"
+
+    @classmethod
+    def file_share(
+        cls,
+        source: str,
+        target_site_url: str,
+        target_list: str,
+        target_list_relative_path: str | None = None,
+    ) -> "MigrationTask":
+        """A file-share task (``Add-SPMTTask -FileShareSource …``)."""
+        return cls(
+            kind=FILE_SHARE,
+            file_share_source=source,
+            target_site_url=target_site_url,
+            target_list=target_list,
+            target_list_relative_path=target_list_relative_path,
+        )
+
+    @classmethod
+    def sharepoint(
+        cls,
+        source_site_url: str,
+        target_site_url: str,
+        *,
+        source_list: str | None = None,
+        target_list: str | None = None,
+        source_list_relative_path: str | None = None,
+        target_list_relative_path: str | None = None,
+        migrate_all: bool = False,
+    ) -> "MigrationTask":
+        """A SharePoint task — ``migrate_all``, or a single ``source_list`` → ``target_list``."""
+        return cls(
+            kind=SHAREPOINT,
+            sharepoint_source_site_url=source_site_url,
+            source_list=source_list,
+            source_list_relative_path=source_list_relative_path,
+            target_site_url=target_site_url,
+            target_list=target_list,
+            target_list_relative_path=target_list_relative_path,
+            migrate_all=migrate_all,
+        )
+
+    @classmethod
+    def from_json(cls, definition: str | dict) -> "MigrationTask":
+        """Parse an SPMT JSON task definition (``Add-SPMTTask -JsonDefinition``)."""
+        data = json.loads(definition) if isinstance(definition, str) else dict(definition)
+        if "Tasks" in data:  # a {"Tasks": [...]} wrapper → the first task
+            tasks = data["Tasks"]
+            if not tasks:
+                raise ValueError("no tasks in the JSON definition")
+            data = tasks[0]
+        source = data.get("SourcePath")
+        target = data.get("TargetPath")
+        lists = (data.get("Items") or {}).get("Lists") or []
+        if lists:
+            first = lists[0]
+            return cls(
+                kind=SHAREPOINT,
+                sharepoint_source_site_url=source,
+                target_site_url=target,
+                source_list=first.get("SourceList"),
+                target_list=first.get("TargetList"),
+            )
+        return cls(
+            kind=FILE_SHARE,
+            file_share_source=source,
+            target_site_url=target,
+            target_list=data.get("TargetList"),
+            target_list_relative_path=data.get("TargetListRelativePath"),
+        )
+
+    def to_json(self) -> str:
+        """Serialize to the SPMT JSON task shape (round-trips through :meth:`from_json`)."""
+        if self.kind == SHAREPOINT:
+            data: dict = {"SourcePath": self.sharepoint_source_site_url, "TargetPath": self.target_site_url}
+            if not self.migrate_all:
+                data["Items"] = {"Lists": [{"SourceList": self.source_list, "TargetList": self.target_list}]}
+        else:
+            data = {
+                "SourcePath": self.file_share_source,
+                "TargetPath": self.target_site_url,
+                "TargetList": self.target_list,
+                "TargetListRelativePath": self.target_list_relative_path,
+            }
+        return json.dumps({name: value for name, value in data.items() if value is not None}, indent=2)
+
+    def label(self) -> str:
+        source = self.file_share_source or self.sharepoint_source_site_url or "?"
+        return f"{self.kind}: {source} -> {self.target_site_url or '?'}"

office365/migration/validators.py

@@ -7,29 +7,12 @@ reports any missing, extra, or mismatched items.
 from __future__ import annotations
 
 import random
-from dataclasses import dataclass, field
 
 from office365.migration.adapters import DataSource, DataTarget
 from office365.migration.manifest import Manifest
+from office365.runtime.verification import VerificationReport
 
-
-@dataclass
-class VerificationReport:
-    source_count: int = 0
-    target_count: int = 0
-    checked: int = 0
-    mismatches: list[str] = field(default_factory=list)
-
-    @property
-    def ok(self) -> bool:
-        return self.source_count == self.target_count and not self.mismatches
-
-    def summary(self) -> str:
-        status = "OK" if self.ok else "MISMATCH"
-        return (
-            f"{status} | source: {self.source_count}, target: {self.target_count}, "
-            f"checksums checked: {self.checked}, issues: {len(self.mismatches)}"
-        )
+__all__ = ["VerificationReport", "verify"]
 
 
 def verify(

office365/onedrive/driveitems/driveItem.py

@@ -249,17 +249,40 @@ class DriveItem(BaseItem):
         Returns:
             DriveItem: The target folder (existing or newly created).
         """
-        from office365.runtime.client_request_exception import ObjectNotFoundException
-
-        names = [name for name in url_path.replace("\\", "/").split("/") if name]
+        names = self._split_path(url_path)
         if not names:
             raise ValueError("Path is empty")
         return_type = DriveItem(self.context)
 
+        def _on_resolved(folder: DriveItem) -> None:
+            return_type._resource_path = folder._resource_path
+            return_type.copy_from(folder)
+
+        self._resolve_path(names, _on_resolved)
+        return return_type
+
+    @staticmethod
+    def _split_path(path: str) -> list[str]:
+        """Split a (server-relative) path into non-empty segments."""
+        return [name for name in path.replace("\\", "/").split("/") if name]
+
+    def _resolve_path(self, names: list[str], on_resolved: Callable[[DriveItem], None]) -> None:
+        """Walk and create the folders in ``names``, then call ``on_resolved`` with the resolved folder.
+
+        Reuses an existing folder per level or creates the missing one. The
+        callback receives a query-bound parent entity, so callers can queue
+        further work (e.g. a file upload) that depends on the parent id. With no
+        names the callback runs synchronously against ``self``.
+
+        Args:
+            names (list[str]): Folder names, relative to this item.
+            on_resolved (Callable[[DriveItem], None]): Invoked with the resolved folder.
+        """
+        from office365.runtime.exceptions import ObjectNotFoundException
+
         def _walk(parent: DriveItem, idx: int) -> None:
             if idx == len(names):
-                return_type._resource_path = parent._resource_path
-                return_type.copy_from(parent)
+                on_resolved(parent)
                 return
 
             child = parent.get_by_path(names[idx])
@@ -282,6 +305,59 @@ class DriveItem(BaseItem):
             self.get_by_path(prefix).get().after_execute(lambda resolved: _walk(resolved, idx + 1))
 
         _walk(self, 0)
+
+    @require_permission(
+        delegated=["Files.ReadWrite", "Files.ReadWrite.All", "Sites.ReadWrite.All"],
+        application=["Files.ReadWrite.All", "Sites.ReadWrite.All"],
+        notes="Ensure a file exists in a drive, uploading its content when missing",
+    )
+    def ensure_file(self, relative_path: str, content: bytes | str = b"", *, on_conflict: str = "skip") -> DriveItem:
+        """Ensure a file exists at the given path, uploading content when needed.
+
+        The file counterpart of :meth:`ensure_folder`: missing parent folders are
+        created (via :meth:`ensure_folder`), then the leaf file is resolved —
+        reusing the existing file or uploading ``content`` when absent. Fully
+        deferred — run the chain with ``execute_query()`` and the returned item
+        addresses the target file:
+
+            >>> file = drive_item.ensure_file("2024/Q1/placeholder.txt").execute_query()
+
+        Args:
+            relative_path (str): File name or path relative to this item, e.g.
+                ``"report.txt"`` or ``"2024/Q1/report.txt"``.
+            content (bytes or str): File content; ``str`` is encoded as UTF-8.
+            on_conflict (str): Behaviour when the file already exists.
+                ``"skip"`` (default) leaves it untouched, so a re-run is a no-op
+                and ``content`` is never sent; ``"replace"`` overwrites it with
+                ``content`` in a single request.
+
+        Returns:
+            DriveItem: The target file (existing or newly uploaded).
+        """
+        from office365.runtime.queries.get_or_create import get_or_create
+
+        if on_conflict not in ("skip", "replace"):
+            raise ValueError(f"on_conflict must be 'skip' or 'replace', got {on_conflict!r}")
+        names = self._split_path(relative_path)
+        if not names:
+            raise ValueError("Path is empty")
+        name = names[-1]
+        data = content.encode("utf-8") if isinstance(content, str) else content
+        return_type = DriveItem(self.context)
+
+        def _on_resolved(parent_item: DriveItem) -> None:
+            return_type._resource_path = parent_item.get_by_path(name)._resource_path
+            if on_conflict == "replace":
+                parent_item.context.add_query(parent_item._build_upload_query(return_type, data))
+                return
+            get_or_create(
+                find=lambda: parent_item.get_by_path(name).get(),
+                create_query=lambda: parent_item._build_upload_query(return_type, data),
+                return_type=return_type,
+                on_conflict="skip",
+            )
+
+        self._resolve_path(names[:-1], _on_resolved)
         return return_type
 
     def create_powerpoint(self, name: str) -> DriveItem:
@@ -351,6 +427,22 @@ class DriveItem(BaseItem):
         self.context.add_query(qry)
         return self
 
+    def delete_object(self, bypass_shared_lock: bool = False) -> Self:
+        """Deletes the driveItem.
+
+        Args:
+            bypass_shared_lock: Send ``Prefer: bypass-shared-lock`` so the delete
+                succeeds even when the item 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 extract_sensitivity_labels(
         self,
     ) -> ClientResult[ExtractSensitivityLabelsResult]:
@@ -464,6 +556,24 @@ class DriveItem(BaseItem):
         self.context.add_query(qry)
         return qry.return_type
 
+    def _build_upload_query(self, item: DriveItem, content: bytes | None) -> ServiceOperationQuery[DriveItem]:
+        """Build (but do not queue) the ``PUT .../content`` query for ``item``.
+
+        Shared by :meth:`upload` and :meth:`ensure_file` — the latter needs a
+        query it can hand to ``get_or_create``'s deferred create slot.
+
+        Args:
+            item (DriveItem): The file that receives the content.
+            content (bytes or None): The binary content to upload.
+        """
+        qry = ServiceOperationQuery(item, "content", None, content, None, item)
+
+        def _modify_query(request: RequestOptions) -> None:
+            request.method = HttpMethod.Put
+
+        qry.before_execute(_modify_query)
+        return qry
+
     @require_permission(
         delegated=["Files.ReadWrite", "Files.ReadWrite.All", "Sites.ReadWrite.All"],
         application=["Files.ReadWrite.All", "Sites.ReadWrite.All"],
@@ -474,13 +584,7 @@ class DriveItem(BaseItem):
 
         return_type = DriveItem(self.context, UrlPath(name, self.resource_path))
         self.children.add_child(return_type)
-
-        qry = ServiceOperationQuery(return_type, "content", None, content, None, return_type)
-
-        def _modify_query(request: RequestOptions) -> None:
-            request.method = HttpMethod.Put
-
-        self.context.add_query(qry).before_execute(_modify_query)
+        self.context.add_query(self._build_upload_query(return_type, content))
         return return_type
 
     def upload_file(self, path_or_file: str | PathLike | IOBase) -> DriveItem:

office365/onedrive/termstore/groups/collection.py

@@ -1,7 +1,6 @@
 from office365.directory.permissions.require_permission import require_permission
 from office365.entity_collection import EntityCollection
 from office365.onedrive.termstore.groups.group import Group
-from office365.runtime.client_request_exception import ClientRequestException, DuplicatedObjectException
 
 
 class GroupCollection(EntityCollection[Group]):
@@ -33,12 +32,6 @@ class GroupCollection(EntityCollection[Group]):
 
     def ensure(self, name: str) -> Group:
         """Gets existing group by name or creates a new one (idempotent)."""
-        return_type = self.add(name)
+        from office365.runtime.queries.get_or_create import create_or_get
 
-        def _on_error(error: ClientRequestException):
-            if not isinstance(error, DuplicatedObjectException):
-                raise error
-            self.get_by_name(name).after_execute(lambda existing: return_type.copy_from(existing), execute_first=True)
-
-        return_type.on_error(_on_error)
-        return return_type
+        return create_or_get(create=lambda: self.add(name), find=lambda: self.get_by_name(name))

office365/onedrive/termstore/sets/collection.py

@@ -6,7 +6,6 @@ from office365.directory.permissions.require_permission import require_permissio
 from office365.entity_collection import EntityCollection
 from office365.onedrive.termstore.sets.name import LocalizedName
 from office365.onedrive.termstore.sets.set import Set
-from office365.runtime.client_request_exception import ClientRequestException, DuplicatedObjectException
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.v4.entity import EntityPath
 from office365.runtime.queries.create_entity import CreateEntityQuery
@@ -76,12 +75,6 @@ class SetCollection(EntityCollection[Set]):
 
     def ensure_set(self, name: str) -> Set:
         """Gets existing set by name or creates a new one (idempotent)."""
-        return_type = self.add(name)
+        from office365.runtime.queries.get_or_create import create_or_get
 
-        def _on_error(error: ClientRequestException):
-            if not isinstance(error, DuplicatedObjectException):
-                raise error
-            self.get_by_name(name).after_execute(lambda existing: return_type.copy_from(existing), execute_first=True)
-
-        return_type.on_error(_on_error)
-        return return_type
+        return create_or_get(create=lambda: self.add(name), find=lambda: self.get_by_name(name))

office365/onedrive/termstore/terms/collection.py

@@ -4,7 +4,6 @@ from office365.directory.permissions.require_permission import require_permissio
 from office365.entity_collection import EntityCollection
 from office365.onedrive.termstore.terms.label import LocalizedLabel
 from office365.onedrive.termstore.terms.term import Term
-from office365.runtime.client_request_exception import ClientRequestException, DuplicatedObjectException
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.v4.entity import EntityPath
 from office365.runtime.queries.create_entity import CreateEntityQuery
@@ -50,13 +49,7 @@ class TermCollection(EntityCollection[Term]):
         return return_type
 
     def ensure(self, label: str) -> Term:
-        return_type = self.add(label)
+        """Gets an existing term by label or creates it (idempotent)."""
+        from office365.runtime.queries.get_or_create import create_or_get
 
-        def _on_error(error: ClientRequestException):
-            if not isinstance(error, DuplicatedObjectException):
-                raise error
-
-            self.get_by_label(label).after_execute(lambda existing: return_type.copy_from(existing), execute_first=True)
-
-        return_type.on_error(_on_error)
-        return return_type
+        return create_or_get(create=lambda: self.add(label), find=lambda: self.get_by_label(label))

office365/onedrive/workbooks/workbook.py

@@ -17,11 +17,18 @@ from office365.onedrive.workbooks.worksheets.collection import (
 )
 from office365.runtime.client_result import ClientResult
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.limits import Limit, LimitKind, limit
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.function import FunctionQuery
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 
+_DOC = "https://learn.microsoft.com/en-us/graph/throttling-limits"
 
+
+@limit(
+    Limit("excel", 5_000, LimitKind.SUPPORTED, "requests", "app", doc=_DOC, window_seconds=10),
+    Limit("excel", 1_500, LimitKind.SUPPORTED, "requests", "app+tenant", doc=_DOC, window_seconds=10),
+)
 class Workbook(Entity):
     """The top-level object that contains related workbook objects such as worksheets, tables, and ranges."""
 

office365/outlook/contacts/folders/collection.py

@@ -1,6 +1,5 @@
 from office365.delta_collection import DeltaCollection
 from office365.outlook.contacts.folders.folder import ContactFolder
-from office365.runtime.client_request_exception import ClientRequestException, DuplicatedObjectException
 
 
 class ContactFolderCollection(DeltaCollection[ContactFolder]):
@@ -18,18 +17,10 @@ class ContactFolderCollection(DeltaCollection[ContactFolder]):
         return super().add(**kwargs)
 
     def ensure(self, display_name: str) -> ContactFolder:
-        """Gets existing group by name or creates a new one (idempotent)."""
-        return_type = self.add(display_name)
-
-        def _on_name_exists(error: ClientRequestException):
-            if not isinstance(error, DuplicatedObjectException):
-                raise error
-            self.get_by_name(display_name).after_execute(
-                lambda existing: return_type.copy_from(existing), execute_first=True
-            )
-
-        return_type.on_error(_on_name_exists)
-        return return_type
+        """Gets an existing folder by name or creates it (idempotent)."""
+        from office365.runtime.queries.get_or_create import create_or_get
+
+        return create_or_get(create=lambda: self.add(display_name), find=lambda: self.get_by_name(display_name))
 
     def get_by_name(self, display_name: str) -> ContactFolder:
         """Returns the group with the specified name."""

office365/runtime/auth/authentication_context.py

@@ -381,6 +381,11 @@ class AuthenticationContext:
         self._authenticate = provider.authenticate_request
         return self
 
+    @property
+    def is_configured(self) -> bool:
+        """Whether an authentication provider has been set on this context."""
+        return self._authenticate is not None
+
     def authenticate_request(self, request: RequestOptions) -> None:
         """Authenticate the HTTP request
 

office365/runtime/client_object.py

@@ -7,6 +7,7 @@ from typing import (
     Dict,
     List,
     Optional,
+    Tuple,
     TypeVar,
 )
 
@@ -16,6 +17,7 @@ from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.converters.value import _add_type_metadata, declared_type, deserialize_value, serialize_value
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.limits import Limit, LimitDecl, collect_class_limits, collect_limit_meta
 from office365.runtime.odata.json_format import ODataJsonFormat
 from office365.runtime.odata.query_options import QueryOptions
 from office365.runtime.paths.resource_path import ResourcePath
@@ -32,6 +34,8 @@ class ClientObject:
     """Base client object which defines named properties and relationships of an entity."""
 
     _odata_meta: dict[str, ODataPropertyMeta] = {}
+    _limit_meta: dict[str, Tuple[LimitDecl, ...]] = {}
+    _class_limit_decls: Tuple[LimitDecl, ...] = ()
 
     def __init_subclass__(cls, **kwargs: object) -> None:
         super().__init_subclass__(**kwargs)
@@ -43,6 +47,8 @@ class ClientObject:
                 m.attr = attr_name
                 meta[m.name] = m
         cls._odata_meta = meta
+        cls._limit_meta = collect_limit_meta(cls)
+        cls._class_limit_decls = collect_class_limits(cls)
 
     def __init__(
         self,
@@ -114,6 +120,13 @@ class ClientObject:
         """Names of properties marked ``@odata(persist=True)``."""
         return {name for name, m in type(self)._odata_meta.items() if m.persist}
 
+    @classmethod
+    def declared_limits(cls) -> Tuple[Limit, ...]:
+        """The limits declared on this class and its methods/properties (``@limit``)."""
+        class_limits = tuple(decl.limit for decl in cls._class_limit_decls)
+        member_limits = tuple(decl.limit for decls in cls._limit_meta.values() for decl in decls)
+        return (*class_limits, *member_limits)
+
     def execute_query(self) -> Self:
         """
         Submits all pending requests to the server.
@@ -133,6 +146,7 @@ class ClientObject:
         success_callback=None,
         failure_callback=None,
         exceptions=(ClientRequestException,),
+        is_retriable=None,
     ) -> Self:
         """Executes the current set of data retrieval queries and method invocations and retries it if needed.
 
@@ -144,6 +158,9 @@ class ClientObject:
             success_callback (callable): A callback to call if the request executes successfully.
             failure_callback (callable): A callback to call if the request fails to execute.
             exceptions (tuple): Tuple of exceptions that we retry.
+            is_retriable (callable): Optional predicate deciding whether a caught
+                exception is retried. Defaults to transient errors; pass
+                ``retry_on(...)`` to also retry otherwise-permanent errors.
         """
         self.context.execute_query_retry(
             max_retry=max_retry,
@@ -153,6 +170,7 @@ class ClientObject:
             success_callback=success_callback,
             failure_callback=failure_callback,
             exceptions=exceptions,
+            is_retriable=is_retriable,
         )
         return self