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

office365/runtime/retry.py

@@ -8,11 +8,16 @@ jitter (so a fleet of clients doesn't retry in lock-step).
 from __future__ import annotations
 
 import random
+from functools import wraps
 from time import sleep
 from typing import Any, Callable, Optional, Tuple, Type
 
+from typing_extensions import ParamSpec
+
 from office365.runtime.client_request_exception import ClientRequestException
 
+_P = ParamSpec("_P")
+
 TRANSIENT_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
 
 
@@ -85,8 +90,40 @@ def backoff_delay(attempt: int, base: int, max_delay: Optional[int] = None, jitt
     return delay
 
 
-def retry(
+def _run_with_retry(
     func: Callable[[], Any],
+    *,
+    max_retry: int,
+    timeout_secs: int,
+    max_delay: Optional[int],
+    jitter: bool,
+    exceptions: Tuple[Type[Exception], ...],
+    is_retriable: Callable[[Exception], bool],
+    on_failure: Optional[Callable[[int, Exception], Optional[int]]],
+    on_success: Optional[Callable[[Any], None]],
+) -> Any:
+    last_ex: Exception | None = None
+    for attempt in range(1, max_retry + 1):
+        try:
+            result = func()
+            if callable(on_success):
+                on_success(result)
+            return result
+        except exceptions as e:
+            if not callable(is_retriable) or not is_retriable(e):
+                raise
+            last_ex = e
+            retry_after: Optional[int] = None
+            if callable(on_failure):
+                retry_after = on_failure(attempt, e)
+            delay = retry_after if retry_after is not None else backoff_delay(attempt, timeout_secs, max_delay, jitter)
+            sleep(delay)
+    assert last_ex is not None
+    raise last_ex
+
+
+def retry(
+    func: Optional[Callable[[], Any]] = None,
     max_retry: int = 5,
     timeout_secs: int = 5,
     max_delay: Optional[int] = None,
@@ -96,20 +133,27 @@ def retry(
     on_failure: Optional[Callable[[int, Exception], Optional[int]]] = None,
     on_success: Optional[Callable[[Any], None]] = None,
 ) -> Any:
-    """Run ``func``, retrying transient failures with exponential backoff.
+    """Run ``func`` with retries — or, called without ``func``, return a decorator.
 
     Permanent failures re-raise immediately; the last exception is re-raised
-    once retries are exhausted.
+    once retries are exhausted. The delay between attempts is exponential with
+    jitter (:func:`backoff_delay`); when ``on_failure`` returns a delay (e.g.
+    the server's ``Retry-After`` via :func:`retry_after_delay`) that value
+    overrides the backoff.
+
+    Two forms::
 
-    The delay between attempts is exponential with jitter (``backoff_delay``);
-    when ``on_failure`` returns a delay (e.g. the server's ``Retry-After`` via
-    :func:`retry_after_delay`) that value overrides the backoff.
+        retry(do_request, max_retry=3)  # run now (existing behaviour)
+
+
+        @retry(max_retry=3)  # decorate a callable
+        def do_request(): ...
 
     Args:
-        func: Callable to execute
+        func: Callable to execute. Omit to get a decorator.
         max_retry: Maximum number of retry attempts
         timeout_secs: Base delay for exponential backoff (seconds)
-        max_delay: Optional cap on the exponential delay (seconds)
+        max_delay: Optional cap for the exponential delay (seconds)
         jitter: Whether to randomize the delay (default True)
         exceptions: Exception types that are candidates for retry
         is_retriable: Classifier deciding whether a caught exception is retried
@@ -117,21 +161,43 @@ def retry(
             may return a retry delay (seconds) to override the backoff
         on_success: Called with ``func()`` result on success
     """
-    last_ex: Exception | None = None
-    for attempt in range(1, max_retry + 1):
-        try:
-            result = func()
-            if callable(on_success):
-                on_success(result)
-            return result
-        except exceptions as e:
-            if not callable(is_retriable) or not is_retriable(e):
-                raise
-            last_ex = e
-            retry_after: Optional[int] = None
-            if callable(on_failure):
-                retry_after = on_failure(attempt, e)
-            delay = retry_after if retry_after is not None else backoff_delay(attempt, timeout_secs, max_delay, jitter)
-            sleep(delay)
-    assert last_ex is not None
-    raise last_ex
+    options = {
+        "max_retry": max_retry,
+        "timeout_secs": timeout_secs,
+        "max_delay": max_delay,
+        "jitter": jitter,
+        "exceptions": exceptions,
+        "is_retriable": is_retriable,
+        "on_failure": on_failure,
+        "on_success": on_success,
+    }
+    if func is None:
+
+        def decorator(fn: Callable[_P, Any]) -> Callable[_P, Any]:
+            @wraps(fn)
+            def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> Any:
+                return _run_with_retry(lambda: fn(*args, **kwargs), **options)  # type: ignore[arg-type]
+
+            return wrapper
+
+        return decorator
+    return _run_with_retry(func, **options)  # type: ignore[arg-type]
+
+
+def retry_on(*exception_types: Type[Exception]) -> Callable[[Exception], bool]:
+    """Return a predicate that retries only the given exception types.
+
+    By default only transient failures are retried (HTTP 408/429/500/502/503/504
+    or non-HTTP errors). Use this as ``is_retriable`` to opt into retrying
+    failures the runtime does not consider transient - for example a file that
+    is locked while a user has it open (HTTP 423)::
+
+        from office365.runtime.exceptions import FileLockedException
+        from office365.runtime.retry import retry_on
+
+        folder.upload_file(name, content).execute_query_retry(is_retriable=retry_on(FileLockedException))
+
+    Args:
+        exception_types: Exception classes that should be retried.
+    """
+    return lambda ex: isinstance(ex, exception_types)

office365/runtime/transport/base.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Tuple
+from typing import Any, Tuple
 
 from requests import Response
 from typing_extensions import Self
@@ -37,6 +37,11 @@ class BaseTransport(ABC):
         """Transport-level request timeout in seconds."""
         return None
 
+    @property
+    def auth(self) -> Any | None:
+        """Transport-level authentication handler, e.g. ``session.auth``."""
+        return None
+
     def close(self) -> None:  # noqa: B027
         """Release transport resources (connections, etc.)."""
 

office365/runtime/transport/requests_transport.py

@@ -44,6 +44,10 @@ class RequestsTransport(BaseTransport):
     def timeout(self) -> int | Tuple[int, int] | None:
         return self._timeout
 
+    @property
+    def auth(self) -> Any | None:
+        return self._session.auth
+
     def execute(self, request: RequestOptions) -> Response:
         kwargs: dict[str, Any] = {"headers": request.headers}
         if request.verify is not None:

office365/runtime/transport/throttled_transport.py

@@ -0,0 +1,67 @@
+"""Transport decorator that paces requests through a shared rate limiter.
+
+Wraps any :class:`~office365.runtime.transport.base.BaseTransport` so every
+request is gated by a shared :class:`~office365.runtime.http.throttling.RateLimiter`
+before it is sent and every response (or error's response) is fed back into it.
+The wrapper is transport-agnostic — it composes with ``requests`` today and with
+an async transport later, and it keeps the pacing at the single I/O boundary so
+call sites stay free of side effects.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Tuple
+
+from office365.runtime.http.throttling import paced
+from office365.runtime.transport.base import BaseTransport
+
+if TYPE_CHECKING:
+    from requests import Response
+
+    from office365.runtime.http.request_options import RequestOptions
+    from office365.runtime.http.throttling import RateLimiter
+
+
+class ThrottledTransport(BaseTransport):
+    """Decorates a transport with fleet-wide pacing from a shared limiter.
+
+    Args:
+        inner: The wrapped transport performing the actual I/O.
+        limiter: The shared :class:`RateLimiter` gating the fleet.
+    """
+
+    def __init__(self, inner: BaseTransport, limiter: "RateLimiter") -> None:
+        self._inner = inner
+        self._limiter = limiter
+
+    @property
+    def inner(self) -> BaseTransport:
+        """The wrapped transport."""
+        return self._inner
+
+    @property
+    def limiter(self) -> "RateLimiter":
+        """The shared rate limiter."""
+        return self._limiter
+
+    def execute(self, request: "RequestOptions") -> "Response":
+        return paced(lambda: self._inner.execute(request), self._limiter)
+
+    @property
+    def proxies(self) -> dict[str, str] | None:
+        return self._inner.proxies
+
+    @property
+    def verify(self) -> bool | str:
+        return self._inner.verify
+
+    @property
+    def timeout(self) -> int | Tuple[int, int] | None:
+        return self._inner.timeout
+
+    @property
+    def auth(self) -> Any | None:
+        return self._inner.auth
+
+    def close(self) -> None:
+        self._inner.close()

office365/runtime/verification.py

@@ -0,0 +1,40 @@
+"""Shared reconciliation report for the data pipeline and the migration toolkit.
+
+One report type is returned by every ``verify*`` (``RecordCollection.verify``,
+``List.verify``, ``ImportResult.verify`` and ``migration.verify``), so callers
+reason about reconciliation the same way regardless of the operation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class VerificationReport:
+    """Outcome of a source-vs-target reconciliation.
+
+    ``source_count``/``target_count`` are the expected/found item counts,
+    ``checked`` the number of items checked, ``missing`` the expected keys absent
+    on the target, and ``mismatches`` human-readable issues (content mismatches,
+    unexpected items, ...). ``ok`` is True when the counts match and both lists
+    are empty.
+    """
+
+    source_count: int = 0
+    target_count: int = 0
+    checked: int = 0
+    missing: list[str] = field(default_factory=list)
+    mismatches: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """Whether the source and target reconcile."""
+        return self.source_count == self.target_count and not self.missing 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"checked: {self.checked}, missing: {len(self.missing)}, issues: {len(self.mismatches)}"
+        )

office365/sharepoint/activities/logger.py

@@ -1,17 +1,16 @@
+from uuid import UUID
+
+from typing_extensions import Self
+
+from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity import Entity
+from office365.sharepoint.logger.activityrequest import LogActivityRequest
 
 
 class ActivityLogger(Entity):
     def log_activity(
-        self,
-        operation,
-        list_id,
-        list_item_unique_id,
-        affected_resource_url,
-        item_type,
-        audit_creation_time,
-        is_offline,
+        self, operation, list_id, list_item_unique_id, affected_resource_url, item_type, audit_creation_time, is_offline
     ):
         """Args:
         operation (str):
@@ -38,3 +37,114 @@ class ActivityLogger(Entity):
     @property
     def entity_type_name(self):
         return "Microsoft.SharePoint.Internal.ActivityLogger"
+
+    def feedback_direct(
+        self,
+        operation: str,
+        list_id: UUID,
+        list_item_unique_id: UUID,
+        affected_resource_url: str,
+        item_type: str,
+        json: str,
+    ) -> Self:
+        """FeedbackDirect operation.
+
+        Args:
+            operation (str): Operation parameter
+            list_id (UUID): ListId parameter
+            list_item_unique_id (UUID): ListItemUniqueId parameter
+            affected_resource_url (str): AffectedResourceUrl parameter
+            item_type (str): ItemType parameter
+            json (str): json parameter
+        """
+        qry = ServiceOperationQuery(
+            self,
+            "FeedbackDirect",
+            None,
+            {
+                "Operation": operation,
+                "ListId": list_id,
+                "ListItemUniqueId": list_item_unique_id,
+                "AffectedResourceUrl": affected_resource_url,
+                "ItemType": item_type,
+                "json": json,
+            },
+            None,
+            None,
+        )
+        self.context.add_query(qry)
+        return self
+
+    def feedback_indirect(
+        self,
+        operation: str,
+        list_id: UUID,
+        list_item_unique_id: UUID,
+        affected_resource_url: str,
+        item_type: str,
+        json: str,
+    ) -> Self:
+        """FeedbackIndirect operation.
+
+        Args:
+            operation (str): Operation parameter
+            list_id (UUID): ListId parameter
+            list_item_unique_id (UUID): ListItemUniqueId parameter
+            affected_resource_url (str): AffectedResourceUrl parameter
+            item_type (str): ItemType parameter
+            json (str): json parameter
+        """
+        qry = ServiceOperationQuery(
+            self,
+            "FeedbackIndirect",
+            None,
+            {
+                "Operation": operation,
+                "ListId": list_id,
+                "ListItemUniqueId": list_item_unique_id,
+                "AffectedResourceUrl": affected_resource_url,
+                "ItemType": item_type,
+                "json": json,
+            },
+            None,
+            None,
+        )
+        self.context.add_query(qry)
+        return self
+
+    def log_activity_bulk(
+        self,
+        operation: str,
+        site_id: UUID,
+        web_id: UUID,
+        list_id: UUID,
+        mailbox_type: str,
+        requests: ClientValueCollection[LogActivityRequest],
+    ) -> Self:
+        """LogActivityBulk operation.
+
+        Args:
+            operation (str): Operation parameter
+            site_id (UUID): SiteId parameter
+            web_id (UUID): WebId parameter
+            list_id (UUID): ListId parameter
+            mailbox_type (str): MailboxType parameter
+            requests (ClientValueCollection[LogActivityRequest]): Requests parameter
+        """
+        qry = ServiceOperationQuery(
+            self,
+            "LogActivityBulk",
+            None,
+            {
+                "Operation": operation,
+                "SiteId": site_id,
+                "WebId": web_id,
+                "ListId": list_id,
+                "MailboxType": mailbox_type,
+                "Requests": requests,
+            },
+            None,
+            None,
+        )
+        self.context.add_query(qry)
+        return self

office365/sharepoint/administration/analytics/usage_service.py

@@ -1,5 +1,9 @@
+from typing_extensions import Self
+
 from office365.runtime.paths.resource_path import ResourcePath
+from office365.runtime.queries.function import FunctionQuery
 from office365.runtime.queries.service_operation import ServiceOperationQuery
+from office365.sharepoint.administration.usageentry import UsageEntry
 from office365.sharepoint.entity import Entity
 
 
@@ -20,13 +24,7 @@ class SPAnalyticsUsageService(Entity):
             site (str):
             user (str):
         """
-        payload = {
-            "EventTypeId": event_type_id,
-            "ItemId": item_id,
-            "ScopeId": scope_id,
-            "Site": site,
-            "User": user,
-        }
+        payload = {"EventTypeId": event_type_id, "ItemId": item_id, "ScopeId": scope_id, "Site": site, "User": user}
         qry = ServiceOperationQuery(self, "logevent", None, payload)
         self.context.add_query(qry)
         return self
@@ -34,3 +32,13 @@ class SPAnalyticsUsageService(Entity):
     @property
     def entity_type_name(self):
         return "Microsoft.SharePoint.Administration.SPAnalyticsUsageService"
+
+    def logevent(self, usage_entry: UsageEntry) -> Self:
+        """logevent operation.
+
+        Args:
+            usage_entry (UsageEntry): usageEntry parameter
+        """
+        qry = FunctionQuery(self, "logevent", [usage_entry], None)
+        self.context.add_query(qry)
+        return self