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

office365/runtime/odata/type.py

@@ -1,12 +1,8 @@
 from __future__ import annotations
 
 import datetime
-import importlib
-import inspect
-import pkgutil
 import uuid
-from functools import lru_cache
-from typing import Optional, Sequence, Type
+from typing import Optional, Type
 
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.types.collections import GuidCollection, StringCollection
@@ -20,6 +16,7 @@ _PRIMITIVE_TYPES = {
     "Edm.Single": float,
     "Edm.Double": float,
     "Edm.Binary": bytes,
+    "Edm.Stream": bytes,
     "Edm.DateTimeOffset": datetime.datetime,
     "Edm.DateTime": datetime.datetime,
     "Edm.Duration": datetime.timedelta,
@@ -34,99 +31,44 @@ _PRIMITIVE_TYPES = {
 
 
 class ODataType:
-    """OData type system utilities with enhanced type resolution."""
-
-    def __init__(self, name: str | None = None, is_object_type: bool = False):
-        self._name = name
-        self._client_type = None
-        self._is_object_type = is_object_type
-        self._used_modules = None
-        self._item_client_type = None
-
-    def __repr__(self):
-        return f"ODataType(name={self._name!r}, client_type={self.client_type_name!r})"
-
-    def __str__(self):
-        return self.client_type_name
-
-    @property
-    def client_type_name(self) -> str:
-        """Returns the model type name representation."""
-        if self._client_type:
-            return self._client_type.__name__
-
-        name = self._name
-        if name is None:
-            return ""
-        if name in _PRIMITIVE_TYPES:
-            primitive_type = _PRIMITIVE_TYPES[name]
-            return primitive_type.__name__
-        elif self.is_collection:
-            item_type_name = name[len("Collection(") : -1]
-            self._item_client_type = ODataType(name=item_type_name, is_object_type=self._is_object_type)
-            item_client_name = self._item_client_type.client_type_name
-            if self._is_object_type:
-                return f"EntityCollection[{item_client_name}]"
-            else:
-                return f"ClientValueCollection[{item_client_name}]"
-        else:
-            cls_name = name.split(".")[-1]
-            if cls_name and cls_name[0].islower():
-                cls_name = cls_name[0].upper() + cls_name[1:]
-            return cls_name
-
-    @property
-    def item_client_type(self) -> Optional[ODataType]:
-        """Returns the ODataType for collection items, if this is a collection."""
-        return self._item_client_type
-
-    @property
-    def client_type(self) -> Optional[Type]:
-        """Returns the resolved Python type, or None if not resolved yet."""
-        return self._client_type
-
-    def resolve_client_type(self, modules: Sequence[str]) -> Optional[Type]:
-        """Resolves and caches the actual Python type."""
-        if self._client_type:
-            return self._client_type
-
-        modules_key = tuple(sorted(modules))
-        resolved = self._resolve_type(modules_key)
-
-        self._client_type = resolved
-        self._used_modules = modules_key
-        return resolved
-
-    @lru_cache(maxsize=512)  # noqa: B019
-    def _resolve_type(self, modules_key: tuple) -> Optional[Type]:
-        """Internal cached resolution."""
-        target_name = self.client_type_name
-
-        def _search_module(module_name: str) -> Optional[Type]:
-            try:
-                module = importlib.import_module(module_name)
-
-                if hasattr(module, target_name):
-                    cls = getattr(module, target_name)
-                    if inspect.isclass(cls):
-                        return cls
-
-                if hasattr(module, "__path__"):
-                    for _, name, _ in pkgutil.iter_modules(module.__path__):
-                        full_name = module_name + "." + name
-                        found_class = _search_module(full_name)
-                        if found_class:
-                            return found_class
-
-            except (ImportError, AttributeError):
-                pass
-            return None
+    """Pure OData type-name utilities (no model resolution / code generation)."""
 
-        for m_name in modules_key:
-            result = _search_module(m_name.strip())
-            if result:
-                return result
-        return None
+    @staticmethod
+    def strip_collection(type_name: str | None) -> str | None:
+        """Returns the item type of ``Collection(...)`` or the type itself."""
+        if type_name is not None and type_name.startswith("Collection(") and type_name.endswith(")"):
+            return type_name[len("Collection(") : -1]
+        return type_name
+
+    @staticmethod
+    def is_collection_name(type_name: str | None) -> bool:
+        """Whether the OData type name represents a collection."""
+        return type_name is not None and type_name.startswith("Collection(") and type_name.endswith(")")
+
+    @classmethod
+    def item_type_name(cls, type_name: str | None) -> str | None:
+        """Returns the collection item type name, or the type name itself."""
+        return cls.strip_collection(type_name)
+
+    @staticmethod
+    def normalize_class_name(name: str) -> str:
+        """Pascal-cases the last segment of an OData type reference."""
+        return name[0].upper() + name[1:]
+
+    @classmethod
+    def normalize_type_name(cls, type_name: str | None) -> str | None:
+        """Normalizes an OData type reference to the generated model key.
+
+        Strips ``Collection(...)`` and Pascal-cases the last segment (e.g.
+        ``microsoft.graph.user`` -> ``microsoft.graph.User``).
+        """
+        item_type = cls.strip_collection(type_name)
+        if item_type is None:
+            return None
+        namespace, _, short_name = item_type.rpartition(".")
+        if not namespace:
+            return item_type
+        return f"{namespace}.{cls.normalize_class_name(short_name)}"
 
     @classmethod
     def resolve_type_name(cls, client_type: Type) -> Optional[str]:
@@ -157,12 +99,12 @@ class ODataType:
                 return odata_type
         return None
 
-    @property
-    def is_primitive_type(self) -> bool:
-        """Checks if a type is a known OData primitive type."""
-        return self._name in _PRIMITIVE_TYPES
+    @staticmethod
+    def primitive_type_for(type_name: str | None) -> Optional[Type]:
+        """Returns the Python type for a known OData primitive, if any."""
+        return _PRIMITIVE_TYPES.get(type_name) if type_name is not None else None
 
-    @property
-    def is_collection(self) -> bool:
-        """Check if this type represents a collection."""
-        return self._name is not None and self._name.startswith("Collection(")
+    @staticmethod
+    def is_primitive_name(type_name: str | None) -> bool:
+        """Whether the OData type name is a known primitive."""
+        return type_name in _PRIMITIVE_TYPES

office365/runtime/odata/v3/batch_request.py

@@ -1,19 +1,25 @@
+from __future__ import annotations
+
 import json
 import re
 from email import message_from_bytes
 from email.message import Message
-from typing import Iterator, List, Tuple
+from typing import Iterator, List, Optional, Tuple
 
 import requests
 from requests import Response
 from requests.structures import CaseInsensitiveDict
 
+from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.odata.batch_util import WHOLE_BATCH_REJECT_CODES, WholeBatchRejected
 from office365.runtime.odata.request import ODataRequest
 from office365.runtime.queries.batch import BatchQuery, create_boundary
 from office365.runtime.queries.client_query import ClientQuery
 
+DEFAULT_MAX_BATCH_BYTES = 1024 * 1024  # SharePoint Online conservative request-size cap
+
 
 class ODataBatchV3Request(ODataRequest):
     """Handles OData v3.0 batch requests and responses.
@@ -50,6 +56,87 @@ class ODataBatchV3Request(ODataRequest):
             sub_resp.raise_for_status()
             super().process_response(sub_resp, sub_qry)
 
+    def execute_query_with_retry(
+        self,
+        query: BatchQuery,
+        max_retry: int = 5,
+        base_delay: int = 5,
+        jitter: bool = True,
+    ) -> None:
+        """Execute a batch, retrying only the transiently-failed sub-requests.
+
+        A throttled sub-request (HTTP 429/503) is retried on its own after the
+        longest ``Retry-After`` (or exponential backoff) — already-succeeded
+        sub-requests are not re-applied, so a partial batch failure doesn't
+        duplicate writes. Routes the retry loop through the shared
+        :func:`~office365.runtime.retry.retry` primitive.
+
+        Args:
+            query: The batch query to execute
+            max_retry: Maximum number of retry attempts per sub-request
+            base_delay: Base delay for exponential backoff (seconds)
+            jitter: Whether to randomize the delay (default True)
+        """
+        from office365.runtime.retry import TRANSIENT_STATUS_CODES, response_retry_after, retry
+
+        state: dict = {"pending": query, "retry_after": None}
+
+        def _attempt() -> None:
+            try:
+                response = self.execute_request_direct(self.build_request(state["pending"]))
+            except ClientRequestException as exc:
+                status = getattr(getattr(exc, "response", None), "status_code", None)
+                if status in WHOLE_BATCH_REJECT_CODES:
+                    # Whole-batch transport rejection (nothing was applied) —
+                    # signal callers to split, not mask per-item errors.
+                    raise WholeBatchRejected(state["pending"].queries, exc) from exc
+                raise
+            failures: list[tuple[ClientQuery, Response]] = []
+            retry_after: Optional[int] = None
+            for sub_qry, sub_resp in self._extract_response(response, state["pending"]):
+                if sub_resp.status_code in TRANSIENT_STATUS_CODES:
+                    failures.append((sub_qry, sub_resp))
+                    retry_after = max(retry_after or 0, response_retry_after(sub_resp) or 0)
+                else:
+                    self._raise_for_status(sub_resp)
+                    super(ODataBatchV3Request, self).process_response(sub_resp, sub_qry)
+            if not failures:
+                self.afterExecute(response)
+                return
+            state["retry_after"] = retry_after or None
+            state["pending"] = BatchQuery(query.context, [qry for qry, _ in failures])
+            raise ClientRequestException.from_response(failures[0][1])
+
+        try:
+            retry(
+                _attempt,
+                max_retry=max_retry,
+                timeout_secs=base_delay,
+                jitter=jitter,
+                on_failure=lambda _attempt_num, _ex: state["retry_after"],
+            )
+        except WholeBatchRejected as reject:
+            self._split_and_retry(query, reject, max_retry, base_delay, jitter)
+
+    def _split_and_retry(
+        self,
+        query: BatchQuery,
+        reject: WholeBatchRejected,
+        max_retry: int,
+        base_delay: int,
+        jitter: bool,
+    ) -> None:
+        """Halve a whole-rejected batch and retry each half (down to a single request)."""
+        queries = reject.queries
+        if len(queries) <= 1:
+            first = queries[0]
+            req = first.build_request()
+            message = f"{reject}; a batch of 1 was still rejected — request {req.method} {req.url}"
+            raise ClientRequestException(message, response=reject.response) from reject
+        mid = len(queries) // 2  # noqa: PLR2004
+        for half in (queries[:mid], queries[mid:]):
+            self.execute_query_with_retry(BatchQuery(query.context, half), max_retry, base_delay, jitter)
+
     def _extract_response(self, response: Response, query: BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]:
         """Extract individual responses from a multipart batch response.
 

office365/runtime/odata/v4/batch_request.py

@@ -1,15 +1,21 @@
+from __future__ import annotations
+
 import json
 from typing import Any, Dict, Iterator, List, Optional, Tuple
 
 from requests import Response
 from requests.structures import CaseInsensitiveDict
 
+from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.odata.batch_util import WHOLE_BATCH_REJECT_CODES, WholeBatchRejected
 from office365.runtime.odata.request import ODataRequest
 from office365.runtime.queries.batch import BatchQuery
 from office365.runtime.queries.client_query import ClientQuery
 
+DEFAULT_MAX_BATCH_BYTES = 3 * 1024 * 1024  # Microsoft Graph JSON-batch limit is ~4 MB; conservative cap
+
 
 class ODataV4BatchRequest(ODataRequest):
     """Handles JSON batch requests for OData v4 protocol.
@@ -48,6 +54,88 @@ class ODataV4BatchRequest(ODataRequest):
             sub_resp.raise_for_status()
             super().process_response(sub_resp, sub_qry)
 
+    def execute_query_with_retry(
+        self,
+        query: BatchQuery,
+        max_retry: int = 5,
+        base_delay: int = 5,
+        jitter: bool = True,
+    ) -> None:
+        """Execute a batch, retrying only the transiently-failed sub-requests.
+
+        Per the Microsoft Graph batching guidance, a throttled sub-request
+        (HTTP 429/503) is retried on its own after the longest ``Retry-After``
+        (or exponential backoff) — already-succeeded sub-requests are not
+        re-applied, so a partial batch failure doesn't duplicate writes. Routes
+        the retry loop through the shared
+        :func:`~office365.runtime.retry.retry` primitive.
+
+        Args:
+            query: The batch query to execute
+            max_retry: Maximum number of retry attempts per sub-request
+            base_delay: Base delay for exponential backoff (seconds)
+            jitter: Whether to randomize the delay (default True)
+        """
+        from office365.runtime.retry import TRANSIENT_STATUS_CODES, response_retry_after, retry
+
+        state: dict = {"pending": query, "retry_after": None}
+
+        def _attempt() -> None:
+            try:
+                response = self.execute_request_direct(self.build_request(state["pending"]))
+            except ClientRequestException as exc:
+                status = getattr(getattr(exc, "response", None), "status_code", None)
+                if status in WHOLE_BATCH_REJECT_CODES:
+                    # Whole-batch transport rejection (nothing was applied) —
+                    # signal callers to split, not mask per-item errors.
+                    raise WholeBatchRejected(state["pending"].queries, exc) from exc
+                raise
+            failures: list[tuple[ClientQuery, Response]] = []
+            retry_after: Optional[int] = None
+            for sub_qry, sub_resp in self._extract_response(response, state["pending"]):
+                if sub_resp.status_code in TRANSIENT_STATUS_CODES:
+                    failures.append((sub_qry, sub_resp))
+                    retry_after = max(retry_after or 0, response_retry_after(sub_resp) or 0)
+                else:
+                    self._raise_for_status(sub_resp)
+                    super(ODataV4BatchRequest, self).process_response(sub_resp, sub_qry)
+            if not failures:
+                self.afterExecute(response)
+                return
+            state["retry_after"] = retry_after or None
+            state["pending"] = BatchQuery(query.context, [qry for qry, _ in failures])
+            raise ClientRequestException.from_response(failures[0][1])
+
+        try:
+            retry(
+                _attempt,
+                max_retry=max_retry,
+                timeout_secs=base_delay,
+                jitter=jitter,
+                on_failure=lambda _attempt_num, _ex: state["retry_after"],
+            )
+        except WholeBatchRejected as reject:
+            self._split_and_retry(query, reject, max_retry, base_delay, jitter)
+
+    def _split_and_retry(
+        self,
+        query: BatchQuery,
+        reject: WholeBatchRejected,
+        max_retry: int,
+        base_delay: int,
+        jitter: bool,
+    ) -> None:
+        """Halve a whole-rejected batch and retry each half (down to a single request)."""
+        queries = reject.queries
+        if len(queries) <= 1:
+            first = queries[0]
+            req = first.build_request()
+            message = f"{reject}; a batch of 1 was still rejected — request {req.method} {req.url}"
+            raise ClientRequestException(message, response=reject.response) from reject
+        mid = len(queries) // 2  # noqa: PLR2004
+        for half in (queries[:mid], queries[mid:]):
+            self.execute_query_with_retry(BatchQuery(query.context, half), max_retry, base_delay, jitter)
+
     @staticmethod
     def _extract_response(response: Response, query: BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]:
         """Extracts individual responses from the batch response.

office365/runtime/odata/v4/upload_session.py

@@ -15,3 +15,7 @@ class UploadSession(ClientValue):
     uploadUrl: str | None = None
     expirationDateTime: datetime | None = None
     nextExpectedRanges: StringCollection = field(default_factory=StringCollection)
+
+    @property
+    def entity_type_name(self) -> str:
+        return "microsoft.graph.UploadSession"

office365/runtime/odata/v4/upload_session_request.py

@@ -1,15 +1,14 @@
 from __future__ import annotations
 
 import os
-from typing import BinaryIO, Callable, Optional
+from typing import IO, Callable, Optional
 
 from requests import Response
-from typing_extensions import Self
 
 from office365.runtime.client_request import ClientRequest
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
-from office365.runtime.queries.upload_session import UploadSessionQuery
+from office365.runtime.queries.client_query import ClientQuery
 
 
 class UploadSessionRequest(ClientRequest):
@@ -17,9 +16,11 @@ class UploadSessionRequest(ClientRequest):
 
     def __init__(
         self,
-        file_object: BinaryIO,
+        file_object: IO,
         chunk_size: int,
         chunk_uploaded: Callable[[int], None] | None = None,
+        upload_url: str | None = None,
+        file_size: int | None = None,
     ) -> None:
         """Initialize an upload session request.
 
@@ -27,21 +28,27 @@ class UploadSessionRequest(ClientRequest):
             file_object: The file-like object to upload
             chunk_size: Size of each upload chunk in bytes
             chunk_uploaded: Callback invoked after each chunk is uploaded
+            upload_url: Explicit upload-session URL (when the session was created
+              outside of an ``UploadSessionQuery``, e.g. Microsoft To Do)
+            file_size: Total size override (for streams without a file descriptor)
         """
         super().__init__()
         self._file_object = file_object
         self._chunk_size = chunk_size
         self._chunk_uploaded = chunk_uploaded
+        self._upload_url = upload_url
+        self._file_size = file_size
         self._range_data: Optional[bytes] = None
+        self.last_response: Response | None = None
 
     @property
     def service_root_url(self) -> str:
         return ""
 
-    def build_request(self, query: UploadSessionQuery) -> RequestOptions:  # type: ignore[reportIncompatibleMethodOverride]
+    def build_request(self, query: ClientQuery) -> RequestOptions:
         """Build a request for uploading a single chunk."""
         assert self._range_data is not None
-        upload_url = query.upload_session_url
+        upload_url = self._upload_url or getattr(query, "upload_session_url", None)
         assert upload_url is not None
         request = RequestOptions(upload_url)
         request.method = HttpMethod.Put
@@ -54,18 +61,18 @@ class UploadSessionRequest(ClientRequest):
         request.data = self._range_data
         return request
 
-    def process_response(self, response: Response, query: UploadSessionQuery) -> None:  # type: ignore[reportIncompatibleMethodOverride]
+    def process_response(self, response: Response, query: ClientQuery) -> None:
         """Handle the response after uploading a chunk."""
         response.raise_for_status()
+        self.last_response = response
         if callable(self._chunk_uploaded):
             self._chunk_uploaded(self.range_end)
 
-    def execute_query(self, query: UploadSessionQuery) -> Self:  # type: ignore[reportIncompatibleMethodOverride]
+    def execute_query(self, query: ClientQuery) -> None:
         """Execute the upload query for each chunk."""
         for chunk_data in self._read_next():
             self._range_data = chunk_data
             super().execute_query(query)
-        return self
 
     def _read_next(self):
         """Generate fixed-size chunks from the file object.
@@ -82,7 +89,16 @@ class UploadSessionRequest(ClientRequest):
     @property
     def file_size(self) -> int:
         """Get the total size of the file being uploaded."""
-        return os.fstat(self._file_object.fileno()).st_size
+        if self._file_size is not None:
+            return self._file_size
+        try:
+            return os.fstat(self._file_object.fileno()).st_size
+        except (AttributeError, OSError):
+            pos = self._file_object.tell()
+            self._file_object.seek(0, os.SEEK_END)
+            size = self._file_object.tell()
+            self._file_object.seek(pos)
+            return size
 
     @property
     def range_start(self) -> int:

office365/runtime/operations.py

@@ -0,0 +1,135 @@
+"""Progress reporting for long-running operations.
+
+A structured ``Progress`` payload is passed to an optional ``progress`` hook
+(``ProgressCallback``) as chunks, pages, or files complete — the same pattern
+as azure-storage's ``progress_hook`` or boto3's ``Callback``, adapted to this
+library's deferred execution model: hooks fire during ``execute_query()``.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from itertools import count
+from typing import Any, Callable, Generic, Optional, Sequence, TypeVar
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+@dataclass
+class Progress(Generic[T_co]):
+    """A snapshot of a long-running operation's progress.
+
+    ``T_co`` is the item type carried by ``items`` (e.g. ``Progress[File]``);
+    numeric-only operations use ``Progress[Any]``.
+
+    Attributes:
+        done: Work completed so far (bytes, items, pages...).
+        total: Total work when known; ``None`` for indeterminate operations.
+        stage: Human-readable stage, e.g. ``"uploading"``.
+        items: The batch of items completed by this step, when the operation
+          completes several per step (e.g. a folder scan's files). Treated as
+          read-only; ``None`` for single-item or numeric steps — ``done``
+          already carries the count. Never the full result set.
+    """
+
+    done: int = 0
+    total: Optional[int] = None
+    stage: str = ""
+    items: Optional[Sequence[T_co]] = None
+
+    @property
+    def percent(self) -> Optional[float]:
+        """Completion percentage (0-100), or ``None`` when total is unknown."""
+        if not self.total:
+            return None
+        return min(100.0, self.done / self.total * 100)
+
+
+ProgressCallback = Callable[[Progress[Any]], None]
+
+
+class ProgressTracker:
+    """Shared emitter that turns operation sub-steps into ``Progress`` snapshots.
+
+    Operations that complete in sub-steps (pages, chunks, files, batches) advance
+    a tracker from their ``after_execute`` hooks; it centralizes counting and
+    builds a consistent ``Progress`` payload. Thread-safe, so it can be shared
+    between worker threads (e.g. ``run_parallel``) and a reporting thread.
+
+    Args:
+        progress: Optional ``ProgressCallback`` to invoke per report.
+        total: Total work when known upfront (may be set later via ``set_total``).
+        stage: The operation stage reported on every snapshot.
+
+    Example:
+        >>> tracker = ProgressTracker(callback, total=100, stage="uploading")
+        >>> def _chunk_done(return_type):  # registered via after_execute
+        ...     tracker.advance(len(return_type.value))
+    """
+
+    def __init__(
+        self,
+        progress: ProgressCallback | None = None,
+        *,
+        total: Optional[int] = None,
+        stage: str = "",
+    ) -> None:
+        self._callback = progress
+        self._total = total
+        self._stage = stage
+        self._done = 0
+        self._lock = threading.Lock()
+
+    @property
+    def done(self) -> int:
+        return self._done
+
+    @property
+    def total(self) -> Optional[int]:
+        return self._total
+
+    def set_total(self, total: Optional[int]) -> None:
+        """Set (or update) the total; lets late determinate totals be reported."""
+        self._total = total
+
+    def report(self, done: int, items=None) -> None:
+        """Report an absolute ``done`` count."""
+        with self._lock:
+            self._done = max(self._done, done)
+            done_value = self._done
+        self._emit(done_value, items)
+
+    def advance(self, amount: int = 1, items=None) -> None:
+        """Advance ``done`` by ``amount`` and report it."""
+        with self._lock:
+            self._done += amount
+            done_value = self._done
+        self._emit(done_value, items)
+
+    def _emit(self, done: int, items) -> None:
+        if callable(self._callback):
+            self._callback(Progress(done=done, total=self._total, stage=self._stage, items=items))
+
+
+def query_progress_hook(total: int, progress: ProgressCallback, stage: str = "") -> Callable[[Any], None]:
+    """Return a hook that reports the completion of each of ``total`` queries.
+
+    Register the returned hook per query via ``context.after_execute(hook)``; as
+    the queries complete during ``execute_query()`` a ``Progress`` snapshot is
+    emitted (``done`` = queries completed, ``total`` = the fixed count given
+    here). Generic by design: the stage is caller-supplied (default empty).
+
+    Usage:
+        >>> from office365.runtime.operations import Progress, query_progress_hook
+        >>> hook = query_progress_hook(len(records), my_callback)
+        >>> for qry in queued_queries:
+        ...     context.add_query(qry)
+        ...     context.after_execute(hook)
+    """
+    completed = count(1)
+
+    def _hook(_return_type: Any) -> None:
+        progress(Progress(done=next(completed), total=total, stage=stage))
+
+    return _hook