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

office365/communications/callrecords/call_record.py

@@ -9,9 +9,27 @@ from office365.directory.permissions.identity_set import IdentitySet
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.runtime.client_value_collection import ClientValueCollection
+from office365.runtime.limits import Limit, LimitKind, limit
 from office365.runtime.paths.resource_path import ResourcePath
 
+_DOC = "https://learn.microsoft.com/en-us/graph/throttling-limits"
 
+
+@limit(
+    Limit("call records", 15_000, LimitKind.SUPPORTED, "requests", "app", doc=_DOC, window_seconds=20),
+    Limit("call records", 10_000, LimitKind.SUPPORTED, "requests", "tenant", doc=_DOC, window_seconds=20),
+    Limit("call records", 1_500, LimitKind.SUPPORTED, "requests", "app+tenant", doc=_DOC, window_seconds=20),
+    Limit(
+        "call records",
+        40,
+        LimitKind.SUPPORTED,
+        "requests",
+        "resource",
+        note="per call record",
+        doc=_DOC,
+        window_seconds=20,
+    ),
+)
 class CallRecord(Entity):
     """Represents a single peer-to-peer call or a group call between multiple participants,
     sometimes referred to as an online meeting."""

office365/communications/calls/call.py

@@ -15,14 +15,17 @@ from office365.communications.operations.cancel_media_processing import CancelMe
 from office365.communications.operations.comms import CommsOperation
 from office365.communications.operations.unmute_participant import UnmuteParticipantOperation
 from office365.communications.operations.update_recording_status import UpdateRecordingStatusOperation
+from office365.communications.quotas import CALL_QUOTAS
 from office365.communications.result_info import ResultInfo
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.runtime.client_value_collection import ClientValueCollection
+from office365.runtime.limits import limit
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 
 
+@limit(*CALL_QUOTAS)
 class Call(Entity):
     """
     The call resource is created when there is an incoming call for the application or the application creates a

office365/communications/presences/presence.py

@@ -6,13 +6,16 @@ from typing import Optional
 from typing_extensions import Self
 
 from office365.communications.presences.status_message import PresenceStatusMessage
+from office365.communications.quotas import PRESENCE_QUOTAS
 from office365.entity import Entity
 from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
 from office365.outlook.mail.item_body import ItemBody
+from office365.runtime.limits import limit
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.types.duration import Duration
 
 
+@limit(*PRESENCE_QUOTAS)
 class Presence(Entity):
     """Contains information about a user's presence, including their availability and user activity."""
 

office365/communications/quotas.py

@@ -0,0 +1,66 @@
+"""Microsoft Graph cloud-communications throttling quotas (reference).
+
+Declared on the model with ``@limit(*CALL_QUOTAS)`` etc. (see ``Call``,
+``Presence``, ``VirtualEvent``). Reference-only — the library reacts to the
+server signals (:mod:`office365.runtime.http.throttling`).
+
+Source: https://learn.microsoft.com/en-us/graph/throttling-limits
+"""
+
+from __future__ import annotations
+
+from office365.runtime.limits import Limit, LimitKind
+
+_DOC = "https://learn.microsoft.com/en-us/graph/throttling-limits"
+_SUPPORTED = LimitKind.SUPPORTED
+
+CALL_QUOTAS = (
+    Limit(
+        "cloud communications",
+        50_000,
+        _SUPPORTED,
+        "requests",
+        "app+tenant",
+        note="calls",
+        doc=_DOC,
+        window_seconds=15,
+    ),
+)
+
+PRESENCE_QUOTAS = (
+    Limit(
+        "cloud communications",
+        10_000,
+        _SUPPORTED,
+        "requests",
+        "app+tenant",
+        note="presence",
+        doc=_DOC,
+        window_seconds=30,
+    ),
+)
+
+VIRTUAL_EVENT_QUOTAS = (
+    Limit(
+        "cloud communications",
+        750,
+        _SUPPORTED,
+        "requests",
+        "app",
+        request_type="read",
+        note="virtual events",
+        doc=_DOC,
+        window_seconds=30,
+    ),
+    Limit(
+        "cloud communications",
+        15,
+        _SUPPORTED,
+        "requests",
+        "app",
+        request_type="write",
+        note="virtual events",
+        doc=_DOC,
+        window_seconds=30,
+    ),
+)

office365/communications/virtualevents/virtual_event.py

@@ -1,13 +1,16 @@
 from typing import Optional
 
+from office365.communications.quotas import VIRTUAL_EVENT_QUOTAS
 from office365.communications.virtualevents.presenter import VirtualEventPresenter
 from office365.communications.virtualevents.session import VirtualEventSession
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.outlook.mail.item_body import ItemBody
+from office365.runtime.limits import limit
 from office365.runtime.paths.resource_path import ResourcePath
 
 
+@limit(*VIRTUAL_EVENT_QUOTAS)
 class VirtualEvent(Entity):
     """Represents an abstract base type for a virtual event.
     Base type of virtualEventTownhall and virtualEventWebinar."""

office365/directory/domains/domain.py

@@ -2,14 +2,17 @@ from office365.directory.domains.dns_record import DomainDnsRecord
 from office365.directory.domains.state import DomainState
 from office365.directory.objects.collection import DirectoryObjectCollection
 from office365.directory.permissions.require_permission import require_permission
+from office365.directory.quotas import IDENTITY_QUOTAS
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
+from office365.runtime.limits import limit
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.types.collections import StringCollection
 from office365.runtime.types.odata_property import odata
 
 
+@limit(*IDENTITY_QUOTAS)
 class Domain(Entity):
     """
     Represents a domain associated with the tenant.

office365/directory/licenses/subscribed_sku.py

@@ -2,12 +2,15 @@ from typing import Optional
 
 from office365.directory.licenses.service_plan_info import ServicePlanInfo
 from office365.directory.licenses.units_detail import LicenseUnitsDetail
+from office365.directory.quotas import IDENTITY_QUOTAS
 from office365.entity import Entity
 from office365.runtime.client_value_collection import ClientValueCollection
+from office365.runtime.limits import limit
 from office365.runtime.types.collections import StringCollection
 from office365.runtime.types.odata_property import odata
 
 
+@limit(*IDENTITY_QUOTAS)
 class SubscribedSku(Entity):
     """Contains information about a service SKU that a company is subscribed to."""
 

office365/directory/objects/object.py

@@ -4,13 +4,16 @@ from datetime import datetime
 
 from typing_extensions import Self
 
+from office365.directory.quotas import IDENTITY_QUOTAS
 from office365.entity import Entity
 from office365.runtime.client_result import ClientResult
+from office365.runtime.limits import limit
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.types.collections import StringCollection
 from office365.runtime.types.odata_property import odata
 
 
+@limit(*IDENTITY_QUOTAS)
 class DirectoryObject(Entity):
     """Represents an Azure Active Directory object. The directoryObject type is the base type for many other
     directory entity types."""

office365/directory/quotas.py

@@ -0,0 +1,34 @@
+"""Microsoft Graph identity throttling quotas (reference).
+
+Declared on the model with ``@limit(*IDENTITY_QUOTAS)`` (see ``DirectoryObject``,
+``SubscribedSku``, ``Domain``) — Graph throttles the identity API surface with a
+**ResourceUnits** token bucket plus write quotas. Reference-only: the library
+reacts to the server signals (:mod:`office365.runtime.http.throttling`).
+
+Source: https://learn.microsoft.com/en-us/graph/throttling-limits
+"""
+
+from __future__ import annotations
+
+from office365.runtime.limits import Limit, LimitKind
+
+_DOC = "https://learn.microsoft.com/en-us/graph/throttling-limits"
+_SUPPORTED = LimitKind.SUPPORTED
+
+#: Identity and access quotas (the whole `/users`, `/groups`, ... surface).
+IDENTITY_QUOTAS = (
+    Limit(
+        "identity",
+        3_500,
+        _SUPPORTED,
+        "resource_units",
+        "app+tenant",
+        note="small tenants (<50 users); 5,000 medium (50-500), 8,000 large (>500)",
+        doc=_DOC,
+        window_seconds=10,
+    ),
+    Limit("identity", 150_000, _SUPPORTED, "resource_units", "app", doc=_DOC, window_seconds=20),
+    Limit("identity", 3_000, _SUPPORTED, "requests", "app+tenant", doc=_DOC, window_seconds=150, request_type="write"),
+    Limit("identity", 35_000, _SUPPORTED, "requests", "app", doc=_DOC, window_seconds=300, request_type="write"),
+    Limit("identity", 18_000, _SUPPORTED, "requests", "tenant", doc=_DOC, window_seconds=300, request_type="write"),
+)

office365/entity_collection.py

@@ -4,16 +4,16 @@ from typing import TYPE_CHECKING, Any, Dict, Optional, Type, Union, cast
 
 from office365.entity import Entity
 from office365.runtime.client_object import ClientObjectT
-from office365.runtime.client_object_collection import ClientObjectCollection
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.v4.entity import EntityPath
 from office365.runtime.queries.create_entity import CreateEntityQuery
+from office365.runtime.record_collection import RecordCollection
 
 if TYPE_CHECKING:
     from office365.graph_client import GraphClient
 
 
-class EntityCollection(ClientObjectCollection[ClientObjectT]):
+class EntityCollection(RecordCollection[ClientObjectT]):
     """A collection container which represents a named collections of entities"""
 
     def __init__(

office365/graph_client.py

@@ -65,6 +65,7 @@ from office365.outlook.calendar.rooms.list import RoomList
 from office365.planner.planner import Planner
 from office365.reports.root import ReportRoot
 from office365.runtime.client_runtime_context import ClientRuntimeContext
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.odata.v4.batch_request import DEFAULT_MAX_BATCH_BYTES, ODataV4BatchRequest
 from office365.runtime.odata.v4.json_format import V4JsonFormat
 from office365.runtime.paths.resource_path import ResourcePath
@@ -353,12 +354,37 @@ class GraphClient(ClientRuntimeContext):
         )
         return self
 
+    def with_throttle_priority(self, priority: str = "normal") -> Self:
+        """Send ``x-ms-throttle-priority`` on every request (Graph throttling).
+
+        Per Microsoft Graph, low-priority requests are throttled first and
+        high-priority ones last; the header doesn't change the limits. Use
+        ``"high"`` only for requests initiated by a user (where throttling causes
+        user-visible failures) and ``"low"`` for background work.
+
+        Args:
+            priority: ``"low"``, ``"normal"`` (default) or ``"high"``.
+
+        Raises:
+            ValueError: When ``priority`` isn't one of the accepted values.
+        """
+        value = priority.lower()
+        if value not in ("low", "normal", "high"):
+            raise ValueError("priority must be one of 'low', 'normal', 'high'")
+
+        def _set_header(request: RequestOptions) -> None:
+            request.set_header("x-ms-throttle-priority", value)
+
+        self.pending_request().before_execute(_set_header, once=False)
+        return self
+
     def execute_batch(
         self,
         items_per_batch: int = 20,
         success_callback: Optional[Callable[[List[Any]], None]] = None,
         concurrency: int = 1,
         max_batch_bytes: Optional[int] = None,
+        sequential: bool = False,
     ) -> Self:
         """
         Execute batched requests
@@ -371,21 +397,39 @@ class GraphClient(ClientRuntimeContext):
         writes aren't re-applied. ``success_callback`` runs on the caller thread
         in completion order (not submission order).
 
+        Pass ``sequential=True`` to chain the sub-requests with ``dependsOn`` so
+        Graph runs them in order (a failed dependency yields HTTP 424). Use it
+        only for **ordering-dependent side effects** — read-after-write on the
+        same resource, delete-then-create, parent/child ordering — not for
+        independent requests (Graph's default parallel mode is faster). A batch
+        can't reference another sub-request's response, so it doesn't enable
+        create-then-use-id flows. Implies ``concurrency=1`` because Graph only
+        sequences within a single ``$batch``.
+
         Args:
             items_per_batch: Maximum items per batch (default: 20)
             success_callback: Optional callback for successful requests
             concurrency: Maximum number of concurrent batch requests (default 1)
             max_batch_bytes: Maximum estimated batch payload size (default ~3 MB)
+            sequential: Chain sub-requests with ``dependsOn`` (Graph v4 only).
+
+        Raises:
+            ValueError: When ``sequential`` is combined with ``concurrency > 1``.
         """
+        if sequential and concurrency > 1:
+            raise ValueError("sequential=True requires concurrency=1 (Graph sequences within a batch only)")
         max_bytes = DEFAULT_MAX_BATCH_BYTES if max_batch_bytes is None else max_batch_bytes
         batches = self._split_batches(items_per_batch, max_bytes)
+        if sequential:
+            for batch in batches:
+                batch.sequential = True
         if concurrency <= 1:
             batch_request = ODataV4BatchRequest("", V4JsonFormat())
             batch_request.beforeExecute += self.pending_request().authenticate_request
             for qry in batches:
                 batch_request.execute_query_with_retry(qry)
-                if callable(success_callback) and qry.return_type is not None:
-                    success_callback(qry.return_type)
+                if callable(success_callback) and qry.return_types:
+                    success_callback(qry.return_types)
             return self
 
         self.pending_request()

office365/limits.py

@@ -0,0 +1,66 @@
+"""Unified access to service limits — mechanics, catalogs and discovery.
+
+The library declares limits in three layers:
+
+- **Mechanics** (:mod:`office365.runtime.limits`): :class:`Limit` (a static
+  threshold *or* a rate quota), the :func:`limit` decorator, and the guardrails
+  (:func:`exceeds` / :func:`warn_if_exceeds` / :func:`ensure_within` /
+  :func:`hint`).
+- **Catalogs**: product vocabularies — e.g. ``sharepoint.thresholds.Limits``
+  (SharePoint) and the model-bound Graph quotas (``directory.quotas`` /
+  ``communications.quotas``).
+- **Discovery**: a class carries its limits via ``@limit`` (``declared_limits()``);
+  :func:`limits_of` / :func:`verify_limits` inspect them; :func:`catalog`
+  aggregates every registered source.
+
+Products register their catalogs with :func:`register_catalog`; ``@limit`` on a
+class registers that class automatically (under ``product="model"``).
+"""
+
+from __future__ import annotations
+
+from office365.runtime.limits import (
+    DEFAULT_BATCH_SIZE,
+    SAFE_PAGE_SIZE,
+    Limit,
+    LimitCatalog,
+    LimitDecl,
+    LimitExceededError,
+    LimitKind,
+    LimitReport,
+    bounded,
+    catalog,
+    collect_class_limits,
+    collect_limit_meta,
+    ensure_within,
+    exceeds,
+    hint,
+    limit,
+    limits_of,
+    register_catalog,
+    verify_limits,
+    warn_if_exceeds,
+)
+
+__all__ = [
+    "DEFAULT_BATCH_SIZE",
+    "SAFE_PAGE_SIZE",
+    "Limit",
+    "LimitCatalog",
+    "LimitDecl",
+    "LimitExceededError",
+    "LimitKind",
+    "LimitReport",
+    "bounded",
+    "catalog",
+    "collect_class_limits",
+    "collect_limit_meta",
+    "ensure_within",
+    "exceeds",
+    "hint",
+    "limit",
+    "limits_of",
+    "register_catalog",
+    "verify_limits",
+    "warn_if_exceeds",
+]

office365/migration/__init__.py

@@ -44,7 +44,9 @@ from office365.migration.manifest import Manifest
 from office365.migration.report import MigrationReport, build_report, export_reports
 from office365.migration.runner import MigrationRunner
 from office365.migration.server_job import MigrationServerJob
-from office365.migration.session import MigrationSession
+from office365.migration.session import MigrationSession, SessionTask
+from office365.migration.settings import MigrationSettings
+from office365.migration.tasks import MigrationTask
 from office365.migration.validators import VerificationReport, verify
 
 if TYPE_CHECKING:
@@ -91,10 +93,13 @@ __all__ = [
     "MigrationRunner",
     "MigrationServerJob",
     "MigrationSession",
+    "MigrationSettings",
     "MigrationStats",
+    "MigrationTask",
     "ScanContainer",
     "ScanDefinition",
     "ScanReport",
+    "SessionTask",
     "VerificationReport",
     "build_report",
     "export_reports",

office365/migration/adapters/__init__.py

@@ -9,8 +9,8 @@ SharePoint, the filesystem, and (later) S3 / PostgreSQL / Kafka all plug in here
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Optional
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Callable, Optional
 
 from office365.migration.base import ConflictResolution, MigrationItem
 
@@ -22,7 +22,12 @@ MigrationProgress = Optional[Callable[["Progress"], None]]
 
 
 class DataSource(ABC):
-    """Reads migration items from a source."""
+    """Reads migration items from a source.
+
+    Optional hook (not declared here so ``hasattr`` reflects real support):
+    ``read_permissions(item) -> list[PermissionEntry]`` — the item's ACLs, used
+    for best-effort ``preserve_permissions``. Absent when the source has none.
+    """
 
     @abstractmethod
     def list_items(self, progress: MigrationProgress = None) -> list[MigrationItem]:
@@ -38,7 +43,12 @@ class DataSource(ABC):
 
 
 class DataTarget(ABC):
-    """Writes migration items to a target."""
+    """Writes migration items to a target.
+
+    Optional hooks (not declared here so ``hasattr`` reflects real support),
+    used for best-effort fidelity after a write:
+    ``apply_timestamps(item)`` and ``apply_permissions(item, permissions)``.
+    """
 
     @abstractmethod
     def exists(self, item: MigrationItem) -> bool:

office365/migration/adapters/filesystem.py

@@ -12,9 +12,11 @@ import json
 from datetime import datetime, timezone
 from pathlib import Path
 
-from office365.migration._util import emit_progress, iso, record_to_json
 from office365.migration.adapters import MigrationProgress
 from office365.migration.base import MigrationItem
+from office365.runtime.converters.json_file import record_to_json
+from office365.runtime.converters.scalars import iso
+from office365.runtime.operations import emit_progress
 
 
 class FileSystemSource:
@@ -41,6 +43,7 @@ class FileSystemSource:
                 dest_path=str(path.relative_to(self._root)).replace("\\", "/"),
                 size_bytes=stat.st_size,
                 modified=iso(datetime.fromtimestamp(stat.st_mtime, timezone.utc)),
+                created=iso(datetime.fromtimestamp(stat.st_ctime, timezone.utc)),
             )
             items.append(item)
             emit_progress(progress, done=len(items), stage="planning", items=[item])

office365/migration/assessment/export.py

@@ -12,8 +12,8 @@ from __future__ import annotations
 import os
 from pathlib import Path
 
-from office365.migration._util import write_csv_json
 from office365.migration.assessment.report import AssessmentReport
+from office365.migration.report_io import write_formats
 
 _COLUMNS = ["severity", "category", "location", "message", "suggestion"]
 
@@ -28,7 +28,7 @@ def export_assessment(report: AssessmentReport, output_dir: str | Path) -> list[
     Returns:
         List of written file paths.
     """
-    written = write_csv_json(output_dir, "AssessmentReport", report.to_records(), _COLUMNS)
+    written = write_formats(report.to_records(), output_dir, "AssessmentReport", columns=_COLUMNS)
     written += export_scan_reports(report, output_dir)
     return written
 
@@ -42,10 +42,10 @@ def export_scan_reports(report: AssessmentReport, output_dir: str | Path) -> lis
     for scan in report.scan_reports.values():
         if not scan.records:
             continue
-        written += write_csv_json(
+        written += write_formats(
+            scan.to_records(),
             os.path.join(output_dir, "ScannerReports"),
             f"{scan.name}-detail",
-            scan.to_records(),
-            list(scan.columns),
+            columns=list(scan.columns),
         )
     return written

office365/migration/assessment/issue.py

@@ -1,4 +1,9 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
+from typing import Optional
+
+from office365.runtime.limits import Limit
 
 
 @dataclass
@@ -8,3 +13,17 @@ class AssessmentIssue:
     location: str  # list/folder/field path
     message: str
     suggestion: str = ""
+    risk_code: str = ""  # product-specific scan-assessment code (SPMT), when applicable
+    limit: Optional[Limit] = None  # the authoritative (product-agnostic) limit, when applicable
+
+
+#: SPMT scan-assessment risk codes the library can emit (a subset — the ones tied
+#: to SharePoint service limits). See
+#: https://learn.microsoft.com/en-us/sharepointmigration/spmt-scan-risk-codes
+RISK_CODES: dict[str, str] = {
+    "LIST_VIEW_EXCEED_LIMIT": "The list view shows more items than the list view threshold.",
+    "ITEM_COUNT_EXCEED_INDEX_LIMIT": "Item count is too large to create a column index.",
+    "ITEM_COUNT_EXCEED_LIMIT": "Item count exceeds the per-list maximum.",
+    "LIST_VIEW_LOOKUP_EXCEED_LIMIT": "Lookup/people/managed-metadata columns exceed the list view lookup threshold.",
+    "UNIQUE_PERMISSION_EXCEED_LIMIT": "Unique permissions per list exceed the supported/recommended limit.",
+}

office365/migration/assessment/report.py

@@ -172,6 +172,17 @@ class AssessmentReport(ClientValue):
                 "location": issue.location,
                 "message": issue.message,
                 "suggestion": issue.suggestion,
+                "risk_code": issue.risk_code,
             }
             for issue in self.issues
         ]
+
+    @property
+    def by_risk_code(self) -> dict[str, int]:
+        """Issue counts per SPMT risk code (issues without a code are excluded)."""
+        self._ensure_finalized()
+        counts: dict[str, int] = {}
+        for issue in self.issues:
+            if issue.risk_code:
+                counts[issue.risk_code] = counts.get(issue.risk_code, 0) + 1
+        return counts