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

office365/runtime/client_object_collection.py

@@ -1,6 +1,18 @@
 from __future__ import annotations
 
-from typing import IO, Any, Callable, Dict, Generic, Iterator, List, Optional, Type
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Iterator,
+    List,
+    Optional,
+    Type,
+    cast,
+)
 
 from typing_extensions import Self
 
@@ -8,10 +20,14 @@ from office365.runtime.client_object import ClientObject, ClientObjectT
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.odata.json_format import ODataJsonFormat
+from office365.runtime.operations import Progress
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.types.event_handler import EventHandler
 from office365.runtime.types.exceptions import NotFoundException
 
+if TYPE_CHECKING:
+    from office365.runtime.operations import ProgressCallback
+
 
 class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
     """
@@ -22,8 +38,15 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
     - LINQ-style query operations (filter, order, skip, top)
     - Type-safe object creation and manipulation
     - Event-based loading notifications
+
+    Subclasses backed by a SharePoint list view (list items, files, folders) set
+    ``_list_view_threshold`` so a single-shot load that reaches the threshold warns
+    instead of silently returning a truncated page.
     """
 
+    _list_view_threshold: int | None = None
+    _truncation_hint: str = "page it with get_all(page_size=2000)"
+
     def __init__(
         self,
         context: ClientRuntimeContext,
@@ -45,8 +68,13 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         self._item_type: Type[ClientObjectT] = item_type
         self._page_loaded: EventHandler = EventHandler(False)
         self._paged_mode: bool = False
+        self._page_size: int | None = None
         self._current_pos: int | None = None
         self._next_request_url: str | None = None
+        self._page_headers: dict[str, str] | None = None
+        self._server_paged: bool = False
+        self._next_page: Callable[[], Any] | None = None
+        self._truncation_warned: bool = False
         self._parent = parent
 
     def clear_state(self) -> Self:
@@ -61,7 +89,9 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         """
         if not self._paged_mode:
             self._data = []
+            self._server_paged = False
         self._next_request_url = None
+        self._page_headers = None
         self._current_pos = len(self._data)
         return self
 
@@ -110,6 +140,7 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         if name == "__nextLinkUrl":
             if isinstance(value, str):
                 self._next_request_url = value
+                self._server_paged = True
             else:
                 raise ValueError(f"Invalid value for __nextLinkUrl: expected a string {value}")
         else:
@@ -130,14 +161,33 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         """
         client_object._parent_collection = self
         self._data.append(client_object)
+        self._maybe_warn_truncated()
         return self
 
+    def _maybe_warn_truncated(self) -> None:
+        """Warn once when a single-shot load fills the SharePoint list view threshold.
+
+        A non-paged collection that returns the threshold number of rows may have
+        been silently trimmed by SharePoint, so point the caller at the paged API.
+        """
+        threshold = self._list_view_threshold
+        if threshold is None or self._truncation_warned or self._paged_mode:
+            return
+        if len(self._data) >= threshold:
+            self._truncation_warned = True
+            warnings.warn(
+                f"This collection returned {len(self._data):,} items in a single request and may be "
+                f"truncated at the SharePoint list view threshold ({threshold:,}); {self._truncation_hint}.",
+                UserWarning,
+                stacklevel=3,
+            )
+
     def remove_child(self, client_object: ClientObjectT) -> Self:
         """
         Remove an item from the collection.
 
         Args:
-            client_object: The item to remove
+            client_object: The item to remove from the collection
 
         Returns:
             self: Supports fluent method chaining
@@ -145,16 +195,31 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         self._data = [item for item in self._data if item != client_object]
         return self
 
+    def clear(self) -> Self:
+        """Discard the collection's items, keeping its configuration.
+
+        Unlike :meth:`clear_state` this only drops the loaded/queued entities
+        (``_data``) — used by streaming imports to keep memory bounded between
+        chunks.
+
+        Returns:
+            self: Supports fluent method chaining
+        """
+        self._data = []
+        return self
+
     def __iter__(self) -> Iterator[ClientObjectT]:
         """Iterate through all items, automatically handling paged results."""
         yield from self._data
 
-        # Handle server-side paging
+        # Handle server-side paging: follow __next, yielding each new page only
+        # (a local position, so it stays correct regardless of _current_pos).
         if self._paged_mode:
+            position = len(self._data)
             while self.has_next:
                 self._get_next().execute_query()
-                next_items = self._data[self._current_pos :]
-                yield from next_items
+                yield from self._data[position:]
+                position = len(self._data)
 
     def __len__(self) -> int:
         """Get the current number of loaded items in the collection."""
@@ -168,9 +233,13 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         """Get an item by its index position."""
         return self._data[index]
 
-    def to_json(self, json_format: Optional[ODataJsonFormat] = None) -> list[dict[str, Any]]:  # type: ignore[override]
+    def to_json(self, json_format: Optional[ODataJsonFormat] = None) -> list[dict[str, Any]]:
         """
-        Serialize the collection to JSON format.
+        Serialize the collection to OData JSON format.
+
+        This is **payload serialization** (for request bodies, includes type
+        metadata when requested) — for data export use :meth:`to_records` /
+        :meth:`to_csv` instead.
 
         Args:
             json_format: Serialization options
@@ -178,7 +247,7 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         Returns:
             JSON-serializable list of item dictionaries
         """
-        return [item.to_json(json_format) for item in self._data]
+        return [cast(Dict[str, Any], item.to_json(json_format)) for item in self._data]
 
     def filter(self, expression: str) -> Self:
         """
@@ -247,6 +316,7 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
             self: Supports fluent method chaining
         """
         self._paged_mode = True
+        self._page_size = page_size
         if callable(page_loaded):
             self._page_loaded += page_loaded
         if page_size:
@@ -264,55 +334,90 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
         def _loaded(col: Any) -> None:
             self._page_loaded(self)
 
-        self.context.load(self).after_execute(_loaded)
+        def _capture_headers(resp: Any) -> None:
+            # remember the headers of the first page so subsequent page
+            # requests can re-apply them (e.g. ConsistencyLevel on Graph)
+            request = getattr(resp, "request", None)
+            if self._paged_mode and self._page_headers is None and request is not None:
+                self._page_headers = dict(request.headers)
+
+        self.context.load(self).after_execute(_capture_headers, include_response=True).after_execute(_loaded)
         return self
 
-    def get_all(self, page_size: int | None = None, page_loaded: Callable[[Self], None] | None = None) -> Self:
+    def get_all(
+        self,
+        page_size: int | None = None,
+        page_loaded: Callable[[Self], None] | None = None,
+        progress: "ProgressCallback | None" = None,
+    ) -> Self:
         """
         Load all items in the collection, automatically handling paging.
 
         Args:
             page_size: Items per page (uses server default if None)
-            page_loaded: Callback when each page loads
+            page_loaded: Legacy callback invoked with the loaded collection after
+              each page.
+            progress: Optional hook invoked per page with a ``Progress`` snapshot
+              (``done`` = items loaded so far; ``total`` unknown for server-driven
+              paging, so the bar is indeterminate).
 
         Returns:
             self: Supports fluent method chaining
         """
 
         def _page_loaded(col: ClientObjectCollection) -> None:
+            if callable(progress):
+                progress(Progress(done=len(self._data), stage="loading"))
             if self.has_next:
                 self._get_next().after_execute(_page_loaded)
 
         self.paged(page_size, page_loaded).get().after_execute(_page_loaded)
         return self
 
-    def to_csv(self, file: IO) -> Self:
-        """Export collection items to CSV using ``.select()`` and ``.expand()``.
-
-        Plain select fields (e.g. ``"displayName"``) produce one column.
-        Dotted select fields (e.g. ``"members/displayName"``) walk into an
-        expanded navigation property — one CSV row is emitted per child item.
+    def _can_offset_next(self) -> bool:
+        """Whether the next page can be fetched with a client-driven offset request.
 
-        Usage:
-            >>> client.teams.get_all() \\
-            ...     .select(["displayName", "members/displayName"]) \\
-            ...     .expand(["members"]) \\
-            ...     .to_csv(f) \\
-            ...     .execute_query()
+        Some SharePoint endpoints (e.g. ``SP.Publishing.SitePageService/pages``)
+        never emit a server-side ``__next`` link, even when more items exist.
+        When the client requested an explicit page size and the last page came
+        back full, fall back to ``$skip``/``$top`` paging. Graph is excluded:
+        it always reports ``@odata.nextLink`` and does not honor ``$skip``.
         """
-        from office365.runtime.csv_writer import CollectionCsvWriter
-
-        writer = CollectionCsvWriter(self, file)
-        return self.after_execute(lambda _: writer.write())
+        if not self._paged_mode or not self._page_size or self._next_request_url is not None:
+            return False
+        if self._server_paged:
+            # The server drives paging (``__next``/``$skiptoken``); a ``$skip``
+            # fallback would conflict with the token on the final page.
+            return False
+        from office365.runtime.odata.v3.json_light_format import JsonLightFormat
+
+        json_format = getattr(self.context.pending_request(), "json_format", None)
+        if not isinstance(json_format, JsonLightFormat):
+            return False
+        return len(self.current_page) == self._page_size
 
     def _get_next(self) -> Self:
         """Submit a request to retrieve next collection of items"""
 
+        if self._next_page is not None:
+            # Custom loader (e.g. CAML paging via ListItemCollectionPosition).
+            self._next_page()
+            return self
+
+        _PAGE_EXCLUDED_HEADERS = ("authorization", "content-length")
+
         def _construct_request(request: RequestOptions) -> None:
             request.url = self._next_request_url  # type: ignore[assignment]
+            if self._page_headers:
+                request.headers.update(
+                    {k: v for k, v in self._page_headers.items() if k.lower() not in _PAGE_EXCLUDED_HEADERS}
+                )
 
         if self._next_request_url is None:
-            raise ValueError("Next page not available")
+            if not self._can_offset_next():
+                raise ValueError("Next page not available")
+            self.skip(len(self._data))
+            return self.get()
         return self.get().before_execute(_construct_request)
 
     def first(self, expression: str) -> ClientObjectT:
@@ -373,8 +478,16 @@ class ClientObjectCollection(ClientObject, Generic[ClientObjectT]):
 
     @property
     def has_next(self) -> bool:
-        """Check if more pages are available in server-driven paging."""
-        return self._next_request_url is not None
+        """Check if more pages are available.
+
+        True when the server signalled a next page (``__next``/``@odata.nextLink``)
+        or when a SharePoint collection loaded a full explicit page and the next
+        one can still be fetched via ``$skip``.
+        """
+        if self._next_page is not None:
+            # Custom loader (e.g. CAML): more pages while the last one was full.
+            return self._paged_mode and self._page_size is not None and len(self.current_page) == self._page_size
+        return self._next_request_url is not None or self._can_offset_next()
 
     @property
     def current_page(self) -> List[ClientObjectT]:

office365/runtime/client_request.py

@@ -9,15 +9,18 @@ from typing_extensions import Self
 
 from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.http.throttling import RateLimiter
 from office365.runtime.queries.client_query import ClientQuery
 from office365.runtime.transport.base import BaseTransport
 from office365.runtime.transport.requests_transport import RequestsTransport
+from office365.runtime.transport.throttled_transport import ThrottledTransport
 from office365.runtime.types.event_handler import EventHandler
 
 
 class ClientRequest(ABC):
     def __init__(self, transport: BaseTransport | None = None):
         self._transport = transport or RequestsTransport()
+        self._rate_limiter: RateLimiter | None = None
         self.beforeExecute: EventHandler[[RequestOptions]] = EventHandler()
         self.afterExecute: EventHandler[[Response]] = EventHandler()
         self.onError: EventHandler[[ClientRequestException]] = EventHandler()
@@ -31,6 +34,11 @@ class ClientRequest(ABC):
     def transport(self, value: BaseTransport) -> None:
         self._transport = value
 
+    @property
+    def rate_limiter(self) -> RateLimiter | None:
+        """The shared rate limiter pacing this request's transport, if any."""
+        return self._rate_limiter
+
     def with_transport(
         self,
         proxies: dict[str, str] | None = None,
@@ -41,7 +49,8 @@ class ClientRequest(ABC):
         """Configure the HTTP transport (proxy, SSL, timeout, custom session).
 
         All parameters are optional.  Per-request values (``request.proxies``,
-        ``request.verify``) take precedence over transport-level values.
+        ``request.verify``) take precedence over transport-level values. A rate
+        limiter configured with :meth:`with_rate_limit` is preserved.
 
         Args:
             proxies: Proxy URLs (e.g. ``{"https": "http://proxy:8080"}``)
@@ -58,6 +67,46 @@ class ClientRequest(ABC):
             verify=True if verify is None else verify,
             timeout=timeout,
         )
+        if self._rate_limiter is not None:
+            self._transport = ThrottledTransport(self._transport, self._rate_limiter)
+        return self
+
+    def with_rate_limit(self, health_threshold: int = 80, min_interval: float = 0.0) -> Self:
+        """Pace every request of this request through a new shared rate limiter.
+
+        Control plane: wraps the transport so the whole fleet — including the
+        parallel batches dispatched by a context's ``execute_batch`` — is gated
+        by ``Retry-After`` / ``X-SharePointHealthScore`` as a group. Unlike the
+        ``after_execute`` observation hooks (``rate_limit_hook`` /
+        ``throttle_guard``), this acts on the signals without affecting error
+        propagation. Re-applying replaces the limiter (the underlying transport
+        is not stacked).
+
+        Args:
+            health_threshold: Health score at/above which the group paces.
+            min_interval: Minimum pause applied on a high health score (seconds).
+
+        Returns:
+            Self: Supports method chaining
+        """
+        return self.with_rate_limiter(RateLimiter(health_threshold=health_threshold, min_interval=min_interval))
+
+    def with_rate_limiter(self, limiter: RateLimiter) -> Self:
+        """Pace every request through a caller-provided shared rate limiter.
+
+        Used to share one limiter across a fleet of contexts/clones (see
+        :meth:`RateLimiter.bind`). Re-applying replaces the limiter without
+        stacking wrappers.
+
+        Args:
+            limiter: The shared :class:`RateLimiter` gating the fleet.
+
+        Returns:
+            Self: Supports method chaining
+        """
+        inner = self._transport.inner if isinstance(self._transport, ThrottledTransport) else self._transport
+        self._rate_limiter = limiter
+        self._transport = ThrottledTransport(inner, limiter)
         return self
 
     @property
@@ -104,6 +153,22 @@ class ClientRequest(ABC):
         once: bool = True,
         condition: Optional[Callable[[], bool]] = None,
     ) -> Self:
+        """Register a handler that **handles** (and therefore swallows) an error.
+
+        Once any handler is registered, :meth:`execute_query` dispatches the
+        error to it and does not re-raise — this powers the library's
+        create-if-not-exists flows. It is a control hook, not an observation
+        hook: do not attach a limiter or a pure reporter here, or request
+        failures will be silently suppressed (breaking retries). Use
+        ``after_execute`` / ``throttle_guard`` for observation.
+
+        Args:
+            action: Callback receiving the error.
+            once: Remove the handler after it fires (default True).
+            condition: Optional predicate; when it returns False the handler is
+                skipped (but still counts as a registered error handler).
+        """
+
         def _process_error(e: ClientRequestException):
             matches = condition is None or condition()
             if matches:
@@ -174,6 +239,17 @@ class ClientRequest(ABC):
         except HTTPError:
             raise ClientRequestException.from_response(response) from None
 
+    def _observe_throttle(self, response: Optional[Response]) -> None:
+        """Feed a sub-response into the transport's shared rate limiter, if any.
+
+        Batch responses carry per-sub-request throttling signals that the
+        transport (which only sees the outer ``200``) cannot observe, so the
+        batch loop surfaces each sub-response here.
+        """
+        limiter = getattr(self._transport, "limiter", None)
+        if limiter is not None:
+            limiter.observe(response)
+
     def execute_request_direct(self, request: RequestOptions) -> Response:
         """Execute the client request"""
         self.beforeExecute(request)

office365/runtime/client_request_exception.py

@@ -1,43 +1,113 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Optional
 
 from requests import RequestException, Response
 
+from office365.runtime.converters.scalars import parse_int
+
+_HEADER_REQUEST_IDS = ("request-id", "client-request-id", "SPRequestGuid")
+
+
+@dataclass(frozen=True)
+class ErrorPayload:
+    """Normalized view of an OData error response, parsed once for classification."""
+
+    code: str = ""
+    message: str = ""
+    details: tuple[dict, ...] = ()
+    status: Optional[int] = None
+
+    @property
+    def hresult(self) -> Optional[str]:
+        """The leading HRESULT of a SharePoint ``code`` (e.g. ``-2147018894``).
+
+        SharePoint encodes the error as ``"<hresult>, <dotnet-type>"`` (locale
+        independent), while Graph uses symbolic codes; returns ``None`` when the
+        code has no numeric prefix.
+        """
+        token = self.code.split(",", 1)[0].strip()
+        return token if token.lstrip("-").isdigit() else None
+
+    @property
+    def error_type(self) -> Optional[str]:
+        """The .NET type name embedded in a SharePoint ``code`` after the comma.
+
+        For ``"-2147018894, Microsoft.SharePoint.SPFileLockException"`` this is
+        ``"Microsoft.SharePoint.SPFileLockException"`` — a locale-independent,
+        self-describing discriminator that avoids matching on translated messages.
+        """
+        if "," not in self.code:
+            return None
+        type_name = self.code.split(",", 1)[1].strip()
+        return type_name or None
+
+
+def _parse_error(response: Response) -> dict:
+    try:
+        error = response.json().get("error", {})
+    except Exception:
+        return {}
+    return error if isinstance(error, dict) else {}
+
+
+def _to_payload(error: dict, response: Response) -> ErrorPayload:
+    msg = error.get("message")
+    message = str(msg.get("value", "")) if isinstance(msg, dict) else str(msg or "")
+    details = error.get("details")
+    return ErrorPayload(
+        code=str(error.get("code") or ""),
+        message=message,
+        details=tuple(d for d in details if isinstance(d, dict)) if isinstance(details, list) else (),
+        status=getattr(response, "status_code", None),
+    )
+
 
 class ClientRequestException(RequestException):
-    """Custom exception for client requests with enhanced error handling."""
+    """Custom exception for client requests with enhanced error handling.
+
+    In addition to ``code`` / ``message`` it surfaces correlation and server
+    diagnostics when the error response provides them (Graph ``innerError``,
+    ``request-id``; SharePoint ``SPRequestGuid`` / ``SPRequestDuration`` /
+    ``X-SharePointHealthScore``).
+    """
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self._error: dict = {}
 
+    #: Specificity of this type when several match a payload; the highest wins
+    #: (ties broken by registration order). Lets catch-alls coexist with the
+    #: concrete types without depending on import order.
+    MATCH_PRIORITY: int = 0
+
+    @classmethod
+    def matches(cls, payload: ErrorPayload) -> bool:
+        """Whether this exception type describes the given error payload."""
+        return False
+
     @classmethod
     def from_response(cls, response: Response) -> ClientRequestException:
         """Factory: parse error response, dispatch to the right exception type.
 
-        Inspects the error payload once and returns a specific subclass
-        (e.g. DuplicatedObjectException), so callers never deal with
-        HTTP status codes or error JSON.
+        Inspects the error payload once and returns the most specific matching
+        subclass (e.g. ``DuplicatedObjectException``), so callers never deal with
+        HTTP status codes or error JSON. ``MATCH_PRIORITY`` decides between
+        overlapping types and registration order breaks ties.
         """
-        try:
-            error = response.json().get("error", {})
-        except Exception:
-            error = {}
-
-        if not isinstance(error, dict):
-            error = {}
-
-        details = error.get("details", [])
-        if (
-            error.get("code") == "nameAlreadyExists"
-            or error.get("code") == "ErrorFolderExists"
-            or any(d.get("code") == "ConflictingObjects" for d in details)
-            or "183" in (error.get("code") or "")
-        ):
-            exc: ClientRequestException = DuplicatedObjectException(response=response)
-        else:
-            exc = cls(response=response)
+        from office365.runtime import exceptions  # noqa: F401 — registers the built-in error types
+
+        error = _parse_error(response)
+        payload = _to_payload(error, response)
+        matches = [
+            (getattr(exc_type, "MATCH_PRIORITY", 0), -index, exc_type)
+            for index, exc_type in enumerate(_ERROR_TYPES)
+            if exc_type.matches(payload)
+        ]
+        exc: ClientRequestException = (
+            max(matches, key=lambda item: item[:2])[2](response=response) if matches else cls(response=response)
+        )
 
         exc._error = error
         if error:
@@ -51,6 +121,24 @@ class ClientRequestException(RequestException):
     def code(self) -> Optional[str]:
         return self._error.get("code")
 
+    @property
+    def hresult(self) -> Optional[str]:
+        """The leading HRESULT of a SharePoint ``code`` (``None`` for Graph codes)."""
+        code = self.code
+        if not code:
+            return None
+        token = code.split(",", 1)[0].strip()
+        return token if token.lstrip("-").isdigit() else None
+
+    @property
+    def error_type(self) -> Optional[str]:
+        """The .NET type name embedded in a SharePoint ``code`` (after the comma)."""
+        code = self.code
+        if not code or "," not in code:
+            return None
+        type_name = code.split(",", 1)[1].strip()
+        return type_name or None
+
     @property
     def message(self) -> str:
         msg = self._error.get("message")
@@ -63,10 +151,69 @@ class ClientRequestException(RequestException):
         msg = self._error.get("message")
         return msg.get("lang") if isinstance(msg, dict) else None
 
+    @property
+    def inner_error(self) -> Optional[dict]:
+        """The Graph ``innerError`` payload (``request-id``, ``date``, ...), if any."""
+        inner = self._error.get("innerError")
+        return inner if isinstance(inner, dict) else None
+
+    @property
+    def request_id(self) -> Optional[str]:
+        """Correlation ID for the failed request, if reported.
+
+        Prefers Graph/SharePoint response headers (``request-id``,
+        ``client-request-id``, ``SPRequestGuid``), then the Graph
+        ``innerError.request-id``.
+        """
+        headers = getattr(self.response, "headers", None) or {}
+        for name in _HEADER_REQUEST_IDS:
+            value = headers.get(name)
+            if value:
+                return value
+        inner = self.inner_error or {}
+        return inner.get("request-id")
+
+    @property
+    def server_guid(self) -> Optional[str]:
+        """SharePoint server request GUID (``SPRequestGuid`` header)."""
+        return (getattr(self.response, "headers", None) or {}).get("SPRequestGuid")
+
+    @property
+    def duration_ms(self) -> Optional[int]:
+        """SharePoint server-side processing time (``SPRequestDuration``), ms."""
+        return parse_int((getattr(self.response, "headers", None) or {}).get("SPRequestDuration"))
+
+    @property
+    def health_score(self) -> Optional[int]:
+        """SharePoint server health score (``X-SharePointHealthScore``)."""
+        return parse_int((getattr(self.response, "headers", None) or {}).get("X-SharePointHealthScore"))
+
+
+# Error types consulted by ``from_response``. The generic runtime types live in
+# ``office365.runtime.exceptions`` and product packages (e.g.
+# ``office365.sharepoint.exceptions``) register their own; both call
+# ``register_error_type`` so the dispatcher stays product-agnostic. Specificity is
+# decided by ``MATCH_PRIORITY`` (registration order breaks ties), not import order.
+_ERROR_TYPES: list[type[ClientRequestException]] = []
+
+
+def register_error_type(exc_type: type[ClientRequestException]) -> None:
+    """Register an error type for ``from_response`` dispatch.
+
+    Modules call this at import time; the dispatcher picks the highest
+    ``MATCH_PRIORITY`` match, breaking ties by registration order (earlier wins).
+    """
+    if exc_type not in _ERROR_TYPES:
+        _ERROR_TYPES.append(exc_type)
+
+
+_LAZY_EXPORTS = ("DuplicatedObjectException", "ObjectNotFoundException")
 
-class DuplicatedObjectException(ClientRequestException):
-    """Raised when creating an object that already exists (HTTP 400 + ConflictingObjects)."""
 
+def __getattr__(name: str):
+    """Backward-compatible re-export of the generic error types (now in ``exceptions``)."""
+    if name in _LAZY_EXPORTS:
+        from office365.runtime import exceptions
 
-class ObjectNotFoundException(ClientRequestException):
-    """Raised when a requested object is not found (HTTP 404 or ResourceNotFound code)."""
+        return getattr(exceptions, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")