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

office365/runtime/exceptions.py

@@ -0,0 +1,105 @@
+"""Generic runtime request exceptions.
+
+Concrete error types shared across products (Graph, SharePoint, ...). They
+self-register with the dispatcher in
+:mod:`office365.runtime.client_request_exception`, which imports this module
+lazily so classification works regardless of import order.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from office365.runtime.client_request_exception import (
+    ClientRequestException,
+    ErrorPayload,
+    register_error_type,
+)
+
+
+class DuplicatedObjectException(ClientRequestException):
+    """Raised when creating an object that already exists (HTTP 400 + ConflictingObjects)."""
+
+    MATCH_PRIORITY = 10
+    _CODES = frozenset({"nameAlreadyExists", "ErrorFolderExists", "-2130575342"})
+
+    @classmethod
+    def matches(cls, payload: ErrorPayload) -> bool:
+        return (
+            payload.hresult in cls._CODES
+            or payload.code.lower() in cls._CODES
+            or any(detail.get("code") == "ConflictingObjects" for detail in payload.details)
+            # The generic ``-1, System.Exception`` carries no code, so fall back to
+            # the (English) message — scoped to that opaque case only.
+            or (payload.hresult == "-1" and "already exists" in payload.message.lower())
+        )
+
+
+class ObjectNotFoundException(ClientRequestException):
+    """Raised when a requested object is not found (HTTP 404 or ResourceNotFound code)."""
+
+    MATCH_PRIORITY = 10
+    _CODES = frozenset({"itemnotfound", "resourcenotfound", "notfound"})
+    _TYPE_NAMES = ("FileNotFoundException", "DirectoryNotFoundException", "ResourceNotFoundException")
+
+    @classmethod
+    def matches(cls, payload: ErrorPayload) -> bool:
+        error_type = (payload.error_type or "").lower()
+        return (
+            "-2147024809" in payload.code  # System.ArgumentException (kept for back-compat)
+            or "-2147024894" in payload.code  # System.IO.FileNotFoundException
+            or payload.code.lower() in cls._CODES
+            or any(name.lower() in error_type for name in cls._TYPE_NAMES)
+        )
+
+
+register_error_type(DuplicatedObjectException)
+register_error_type(ObjectNotFoundException)
+
+
+class FileLockedException(ClientRequestException):
+    """Raised when a file is locked and the requested change is rejected (HTTP 423).
+
+    The usual cause is a **shared lock**: the file is open for coauthoring in
+    Office (web or desktop), so SharePoint/Graph refuses the write. Unlike a
+    check-out lock, a shared lock cannot be broken through the API. See
+    :attr:`GUIDANCE` for the available options.
+
+    HTTP 423 is also used by ``Microsoft.SharePoint.SPFileCheckOutException``;
+    that case is classified separately as
+    :class:`~office365.sharepoint.exceptions.SPFileCheckOutException` (a higher
+    priority match), so this type only claims status-only 423 responses.
+    """
+
+    MATCH_PRIORITY = 10
+    _CODES = ("-2147018894", "spfilelockexception", "resourcelocked")
+
+    GUIDANCE = (
+        "The file is locked - typically because it is open for editing in Office. A shared lock "
+        "cannot be broken through the API. Either retry until the other session closes "
+        "(execute_query_retry(is_retriable=retry_on(FileLockedException))), update metadata only "
+        "with ListItem.update_ex(bypass_shared_lock=True), or - for delete - pass "
+        "bypass_shared_lock=True. The lock holder is available via .lock_owner."
+    )
+
+    @classmethod
+    def matches(cls, payload: ErrorPayload) -> bool:
+        code = payload.code.lower()
+        if any(marker in code for marker in cls._CODES):
+            return True
+        return payload.status == 423  # noqa: PLR2004
+
+    @property
+    def lock_owner(self) -> Optional[str]:
+        """Best-effort display name of the user holding the lock (parsed from the message)."""
+        match = re.search(r"locked for shared use by (.+?)\s*\[", self.message, re.IGNORECASE)
+        return match.group(1).strip() if match else None
+
+    def __str__(self) -> str:
+        owner = self.lock_owner
+        described = f"{super().__str__()} (locked by {owner})" if owner else super().__str__()
+        return f"{described}\n{self.GUIDANCE}"
+
+
+register_error_type(FileLockedException)

office365/runtime/http/prefer.py

@@ -0,0 +1,26 @@
+"""``Prefer`` request-header helpers.
+
+The ``Prefer`` header opts a single request into non-default server behaviour.
+Currently the client exposes the shared-lock bypass used when a file is open
+for editing (e.g. in Office) and would otherwise be rejected with HTTP 423.
+"""
+
+from __future__ import annotations
+
+from office365.runtime.http.request_options import RequestOptions
+
+#: Value of the ``Prefer`` header that bypasses a *shared lock* on a file.
+BYPASS_SHARED_LOCK = "bypass-shared-lock"
+
+
+def prefer_bypass_shared_lock(request: RequestOptions) -> None:
+    """Attach ``Prefer: bypass-shared-lock`` to a request.
+
+    A shared lock (as opposed to a check-out lock) is placed on a file while it
+    is open for coauthoring. Only some operations honour the bypass - notably
+    delete. Content uploads cannot bypass a shared lock.
+
+    Attach it to a single request with ``context.before_execute``, or pass
+    ``bypass_shared_lock=True`` to ``delete_object``.
+    """
+    request.set_header("Prefer", BYPASS_SHARED_LOCK)

office365/runtime/http/throttling.py

@@ -5,12 +5,21 @@ response and ``Retry-After`` on throttled (429/503) responses. Per the current
 Microsoft guidance it does **not** return IETF ``RateLimit-*`` headers — those
 are parsed defensively here in case a proxy or other source provides them.
 
-Two ways to use it:
+Two distinct concerns live here:
 
-- Attach :func:`rate_limit_hook` per query (``after_execute(..., include_response=True)``)
-  or to the request event handler for every response;
-- Wrap a workload in :func:`throttle_guard` for a scoped, self-removing guard
-  that hides the event plumbing entirely.
+**Control** — act on the signals to pace the fleet. :class:`RateLimiter` +
+:func:`paced` (used by ``ThrottledTransport``) gate every send and observe every
+response, including failures, without touching error propagation. This is the
+mature pipeline/transport-policy pattern (Azure ``RetryPolicy``, botocore
+adaptive mode, urllib3 ``Retry``).
+
+**Observability** — report the signals to the caller. :func:`rate_limit_hook`
+and :func:`throttle_guard` attach to the request's ``afterExecute`` event and
+never change control flow. Use these when you only want to *know* about
+throttling; use the limiter when you want to *act* on it.
+
+Note: request ``onError`` handlers mark an error as handled (they swallow it —
+see :meth:`ClientRequest.on_error`), so they must not be used for observation.
 """
 
 from __future__ import annotations
@@ -18,25 +27,65 @@ from __future__ import annotations
 import threading
 import time
 from contextlib import contextmanager
-from dataclasses import astuple, dataclass
-from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional
+from dataclasses import dataclass, fields
+from enum import Enum
+from typing import TYPE_CHECKING, Callable, Iterator, Optional
 
 from requests import Response
 
+from office365.runtime.converters.scalars import parse_int
+
 if TYPE_CHECKING:
     from office365.runtime.client_runtime_context import ClientRuntimeContext
 
 
+class ThrottleProtocol(Enum):
+    """Which API's throttling headers to parse.
+
+    ``AUTO`` (default) reads every known header — Microsoft Graph's
+    ``x-ms-throttle-*`` / ``x-ms-resource-unit`` and SharePoint's
+    ``X-SharePointHealthScore`` / ``RateLimit-*`` — so callers rarely need to
+    pick one. The explicit values are an escape hatch for future quirks.
+    """
+
+    AUTO = "auto"
+    GRAPH = "graph"
+    SHAREPOINT = "sharepoint"
+
+
+#: Fields that carry a server signal (``status`` is context, not a signal).
+_SIGNAL_FIELDS = (
+    "limit",
+    "remaining",
+    "reset",
+    "retry_after",
+    "health_score",
+    "limit_percentage",
+    "resource_unit",
+    "scope",
+    "reason",
+)
+
+
 @dataclass(frozen=True)
 class ThrottleLimits:
-    """Throttling state reported by the server on a successful response.
+    """Throttling state reported by the server, protocol-agnostic.
 
     Attributes:
-        limit: Maximum requests permitted in the current window.
+        limit: Maximum requests permitted in the current window (IETF ``RateLimit-*``).
         remaining: Requests still permitted before throttling kicks in.
         reset: Seconds until the quota window resets.
         retry_after: Seconds the server asks us to wait (``Retry-After``).
         health_score: SharePoint health score (0-100), if reported.
+        limit_percentage: Graph ``x-ms-throttle-limit-percentage`` (0.8-1.8) —
+            how much of the granted limit the app consumed; >= 1.0 means requests
+            are being throttled.
+        resource_unit: Graph ``x-ms-resource-unit`` — the cost of this request.
+        scope: Graph ``x-ms-throttle-scope`` — the throttled scope
+            (``<Scope>/<Limit>/<AppId>/<TenantId|UserId|ResourceId>``).
+        reason: Graph ``x-ms-throttle-information`` (``CPULimitExceeded``,
+            ``WriteLimitExceeded``, ``ResourceUnitLimitExceeded``, ...).
+        status: The HTTP status code.
     """
 
     limit: Optional[int] = None
@@ -44,35 +93,101 @@ class ThrottleLimits:
     reset: Optional[int] = None
     retry_after: Optional[int] = None
     health_score: Optional[int] = None
+    limit_percentage: Optional[float] = None
+    resource_unit: Optional[int] = None
+    scope: Optional[str] = None
+    reason: Optional[str] = None
+    status: Optional[int] = None
+
+    @property
+    def has_signals(self) -> bool:
+        """Whether any throttling signal header was present."""
+        return any(getattr(self, name) is not None for name in _SIGNAL_FIELDS)
+
+
+#: Alias for the newer, protocol-agnostic name.
+ThrottleSignal = ThrottleLimits
+
+_ALL_FIELDS = tuple(f.name for f in fields(ThrottleLimits))
+
+
+def _parse_float(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_graph(response: Response) -> ThrottleLimits:
+    """Parse Microsoft Graph throttling headers (``x-ms-throttle-*``)."""
+    headers = response.headers
+    return ThrottleLimits(
+        retry_after=parse_int(headers.get("Retry-After")),
+        limit_percentage=_parse_float(headers.get("x-ms-throttle-limit-percentage")),
+        resource_unit=parse_int(headers.get("x-ms-resource-unit")),
+        scope=headers.get("x-ms-throttle-scope"),
+        reason=headers.get("x-ms-throttle-information"),
+        status=getattr(response, "status_code", None),
+    )
+
+
+def _parse_sharepoint(response: Response) -> ThrottleLimits:
+    """Parse SharePoint throttling/health headers."""
+    headers = response.headers
+    return ThrottleLimits(
+        limit=parse_int(headers.get("RateLimit-Limit")),
+        remaining=parse_int(headers.get("RateLimit-Remaining")),
+        reset=parse_int(headers.get("RateLimit-Reset")),
+        retry_after=parse_int(headers.get("Retry-After")),
+        health_score=parse_int(headers.get("X-SharePointHealthScore")),
+        status=getattr(response, "status_code", None),
+    )
+
 
+_PARSERS: dict[ThrottleProtocol, Callable[[Response], ThrottleLimits]] = {
+    ThrottleProtocol.GRAPH: _parse_graph,
+    ThrottleProtocol.SHAREPOINT: _parse_sharepoint,
+}
 
-def parse_throttling(response: Response) -> Optional[ThrottleLimits]:
+
+def parse_throttling(
+    response: Response,
+    protocol: ThrottleProtocol = ThrottleProtocol.AUTO,
+) -> Optional[ThrottleLimits]:
     """Parse throttling / health headers from a response into a ``ThrottleLimits``.
 
-    Returns ``None`` when the response carries none of the tracked headers
-    (e.g. a Microsoft Graph response), so hooks can stay silent for other APIs.
+    Returns ``None`` when the response carries none of the tracked headers, so
+    hooks can stay silent for ordinary responses. ``protocol=AUTO`` (default)
+    reads every known header; pass an explicit protocol to restrict it.
 
     Args:
         response: The raw HTTP response.
+        protocol: Which API's headers to read (default ``AUTO``).
 
     Returns:
         ThrottleLimits, or None when no tracked headers are present.
     """
-    limits = ThrottleLimits(
-        limit=_to_int(response.headers.get("RateLimit-Limit")),
-        remaining=_to_int(response.headers.get("RateLimit-Remaining")),
-        reset=_to_int(response.headers.get("RateLimit-Reset")),
-        retry_after=_to_int(response.headers.get("Retry-After")),
-        health_score=_to_int(response.headers.get("X-SharePointHealthScore")),
-    )
-    if any(value is not None for value in astuple(limits)):
-        return limits
-    return None
+    if protocol is ThrottleProtocol.AUTO:
+        # ``Retry-After`` is common to both, so merge rather than short-circuit.
+        graph = _parse_graph(response)
+        sharepoint = _parse_sharepoint(response)
+        limits = ThrottleLimits(
+            **{
+                name: (getattr(graph, name) if getattr(graph, name) is not None else getattr(sharepoint, name))
+                for name in _ALL_FIELDS
+            }
+        )
+    else:
+        limits = _PARSERS[protocol](response)
+    return limits if limits.has_signals else None
 
 
 def rate_limit_hook(callback: Optional[Callable[[ThrottleLimits], None]] = None) -> Callable[[Response], None]:
     """Return an after-execute hook that reports parsed throttling / health state.
 
+    Observation only — it never changes control flow (unlike :class:`RateLimiter`).
     The returned hook is compatible with ``after_execute`` (it expects the raw
     ``Response``). It fires ``callback`` only when the response carries any of
     the tracked headers — silent otherwise.
@@ -123,12 +238,83 @@ def throttle_guard(
         handler -= hook
 
 
-def _to_int(value: Any) -> Optional[int]:
-    """Parse a header value into an int, returning None when absent/invalid."""
+@dataclass(frozen=True)
+class PaceState:
+    """The group gate: a monotonic deadline before which requests must wait.
+
+    Produced only by :func:`pace` (pure) so the pacing policy is trivially
+    testable without a clock, a lock, or a sleep.
+    """
+
+    next_available_at: float = 0.0
+
+
+def pace(
+    state: PaceState,
+    limits: Optional[ThrottleLimits],
+    *,
+    now: float,
+    health_threshold: int = 80,
+    min_interval: float = 0.0,
+    percentage_threshold: float = 0.8,
+    percentage_interval: float = 1.0,
+) -> PaceState:
+    """Pure transition: observed server limits -> next gate state.
+
+    A ``Retry-After`` gates the fleet for that long. A high Graph
+    ``x-ms-throttle-limit-percentage`` (>= ``percentage_threshold``) applies a
+    short, scaled pace so the group eases off *before* being throttled; a high
+    ``X-SharePointHealthScore`` does the same as the farm heats up. Returns
+    ``state`` unchanged when nothing applies.
+
+    Args:
+        state: The current gate state.
+        limits: Parsed throttling/health signals (or ``None``).
+        now: Monotonic "now" (injected — the function reads no clock).
+        health_threshold: Health score at/above which the group paces.
+        min_interval: Minimum pause applied on a high health score.
+        percentage_threshold: Graph limit-percentage at/above which the group paces.
+        percentage_interval: Base pause for the Graph limit-percentage pace
+            (scales 1x..2x across 0.8..1.8).
+    """
+    if limits is None:
+        return state
+    delay = 0.0
+    if limits.retry_after is not None and limits.retry_after > 0:
+        delay = max(delay, float(limits.retry_after))
+    if limits.limit_percentage is not None and limits.limit_percentage >= percentage_threshold:
+        delay = max(delay, percentage_interval * (1.0 + (limits.limit_percentage - percentage_threshold)))
+    if limits.health_score is not None and limits.health_score >= health_threshold:
+        delay = max(delay, (limits.health_score - health_threshold) / 20.0, min_interval)
+    if delay <= 0:
+        return state
+    return PaceState(max(state.next_available_at, now + delay))
+
+
+def wait_delay(state: PaceState, *, now: float) -> float:
+    """Pure: seconds until the gate opens (``0`` when already open)."""
+    return max(0.0, state.next_available_at - now)
+
+
+def paced(func: Callable[[], Response], gate: "RateLimiter") -> Response:
+    """Run ``func`` under a shared rate limiter — the functional guard.
+
+    Mirrors :func:`~office365.runtime.retry.retry`: it waits for the group gate,
+    then feeds the outcome (returned response or ``exception.response``) back to
+    the limiter. No call-site side effects; composable and thread-safe.
+
+    Args:
+        func: Callable performing one request/operation.
+        gate: The shared :class:`RateLimiter` to pace against.
+    """
+    gate.acquire()
     try:
-        return int(value)
-    except (TypeError, ValueError):
-        return None
+        result = func()
+    except Exception as ex:
+        gate.observe(getattr(ex, "response", None))
+        raise
+    gate.observe(result)
+    return result
 
 
 class RateLimiter:
@@ -139,17 +325,38 @@ class RateLimiter:
     before any request is sent it blocks until the group gate is open, and when
     any worker observes throttling it pauses the whole group.
 
-    Opt-in — attach it to a context (or a clone) with :meth:`bind`; the existing
-    per-request retry remains as the safety net.
+    The pacing policy lives in the pure :func:`pace` / :func:`wait_delay`; this
+    class is only the thread-safe state holder with injectable ``clock`` and
+    ``sleep`` (so tests can run without real time). Opt-in — wrap a transport
+    with :class:`~office365.runtime.transport.throttled_transport.ThrottledTransport`
+    or attach it to a context with :meth:`bind`; the existing per-request retry
+    remains as the safety net.
     """
 
     _SLEEP_GRANULARITY = 0.05
 
-    def __init__(self, health_threshold: int = 80, min_interval: float = 0.0) -> None:
-        self._lock = threading.RLock()
-        self._next_available_at = 0.0
+    def __init__(
+        self,
+        health_threshold: int = 80,
+        min_interval: float = 0.0,
+        percentage_threshold: float = 0.8,
+        percentage_interval: float = 1.0,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._lock = threading.Lock()
+        self._state = PaceState()
         self._health_threshold = health_threshold
         self._min_interval = min_interval
+        self._percentage_threshold = percentage_threshold
+        self._percentage_interval = percentage_interval
+        self._clock = clock
+        self._sleep = sleep
+
+    def snapshot(self) -> PaceState:
+        """Return the current gate state (a pure value)."""
+        with self._lock:
+            return self._state
 
     def acquire(self) -> None:
         """Block the calling thread until the group gate opens.
@@ -158,48 +365,43 @@ class RateLimiter:
         """
         while True:
             with self._lock:
-                wait = self._next_available_at - time.monotonic()
+                wait = wait_delay(self._state, now=self._clock())
             if wait <= 0:
                 return
-            time.sleep(min(wait, self._SLEEP_GRANULARITY))
+            self._sleep(min(wait, self._SLEEP_GRANULARITY))
 
     def observe(self, response: Optional[Response]) -> None:
-        """Record throttling signals and pause the group when the server asks.
-
-        A throttled response (``Retry-After``) gates the fleet for that long;
-        a high ``X-SharePointHealthScore`` applies a short, scaled pace so the
-        group eases off as the farm heats up.
-        """
+        """Record throttling signals and pause the group when the server asks."""
         if response is None:
             return
         limits = parse_throttling(response)
         if limits is None:
             return
-        now = time.monotonic()
         with self._lock:
-            if limits.retry_after is not None and limits.retry_after > 0:
-                self._next_available_at = max(self._next_available_at, now + limits.retry_after)
-            if limits.health_score is not None and limits.health_score >= self._health_threshold:
-                pace = (limits.health_score - self._health_threshold) / 20.0
-                self._next_available_at = max(self._next_available_at, now + max(pace, self._min_interval))
+            self._state = pace(
+                self._state,
+                limits,
+                now=self._clock(),
+                health_threshold=self._health_threshold,
+                min_interval=self._min_interval,
+                percentage_threshold=self._percentage_threshold,
+                percentage_interval=self._percentage_interval,
+            )
 
     def bind(self, context: "ClientRuntimeContext") -> "RateLimiter":
-        """Attach this limiter to a context (or ``clone``) — every request paces as a group.
+        """Pace every request of a context (or ``clone``) by wrapping its transport.
 
-        Health signals are read on successful responses (``afterExecute``);
-        throttled responses (429/503) raise before ``afterExecute``, so their
-        ``Retry-After`` is read via ``onError`` instead.
+        Delegates to :meth:`ClientRequest.with_rate_limiter` on the context's
+        request, so the shared limiter gates each send and observes each response
+        (and any error's ``response``).
 
         Args:
-            context: The client context to monitor and gate.
+            context: The client context to gate.
         """
-        request = context.pending_request()
-        request.beforeExecute += lambda _: self.acquire()
-        request.afterExecute += lambda response: self.observe(response)
-        request.onError += lambda ex: self.observe(getattr(ex, "response", None))
+        context.pending_request().with_rate_limiter(self)
         return self
 
     def reset(self) -> None:
         """Clear the current gate (used by tests / recovery)."""
         with self._lock:
-            self._next_available_at = 0.0
+            self._state = PaceState()