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

office365/runtime/limits.py

@@ -0,0 +1,455 @@
+"""Product-agnostic service limits, metadata and guardrails.
+
+A :class:`Limit` describes one service limit — a static threshold *or* a rate
+quota — with its value, kind, unit, scope and docs. Limits are declared on the
+model with the :func:`limit` decorator (mirroring ``@odata`` / ``@require_permission``):
+the declaration is stamped on the callable, appended to its docstring, and
+collected into ``ClientObject._limit_meta``. ``arg=`` also *enforces* a numeric
+argument (warn by default, ``raise`` or ``clamp``).
+
+The helpers :func:`exceeds` / :func:`warn_if_exceeds` / :func:`ensure_within`
+apply a limit imperatively at a call site; :func:`limits_of` / :func:`verify_limits`
+inspect what a method/class declares.
+
+Product packages (e.g. ``office365.sharepoint.thresholds``,
+``office365.graph_limits``) declare the concrete values; this module only owns
+the mechanics so the runtime and every product share them.
+"""
+
+from __future__ import annotations
+
+import inspect
+import warnings
+from dataclasses import dataclass, field
+from enum import Enum
+from functools import wraps
+from typing import Any, Callable, Iterable, Optional, Protocol, Tuple, TypeVar, overload, runtime_checkable
+
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+T = TypeVar("T")
+
+_ON_EXCEED = ("warn", "raise")
+_LIMIT_MARKER = "__limit_decls__"
+
+#: A conservative default page/chunk size that stays below SharePoint's 5,000-item
+#: list view threshold, so paged reads and imports are safe by default.
+SAFE_PAGE_SIZE = 2000
+
+#: Default number of items per OData batch (also SharePoint's bulk-operation limit).
+DEFAULT_BATCH_SIZE = 100
+
+
+class LimitKind(Enum):
+    """How strictly a limit is enforced (per Microsoft's definitions)."""
+
+    BOUNDARY = "boundary"  # absolute, can't be exceeded by design
+    THRESHOLD = "threshold"  # configurable default
+    SUPPORTED = "supported"  # tested value
+
+
+def _human_bytes(value: int) -> str:
+    """Format a byte count as ``250 GB`` when it divides evenly, else ``8,000 bytes``."""
+    for suffix, step in (("TB", 1024**4), ("GB", 1024**3), ("MB", 1024**2), ("KB", 1024)):
+        if value >= step and value % step == 0:
+            return f"{value // step} {suffix}"
+    return f"{value:,} bytes"
+
+
+@dataclass(frozen=True)
+class Limit:
+    """A single service limit — a static threshold or a rate quota.
+
+    Args:
+        name: Human-readable name (e.g. ``"list view threshold"``).
+        value: The numeric limit.
+        kind: :class:`LimitKind` — boundary / threshold / supported.
+        unit: What is counted (``items``, ``bytes``, ``requests``, ...).
+        scope: The object it applies to (``list``, ``file``, ``app+tenant``, ...).
+        note: Extra guidance surfaced in warnings.
+        doc: Link to the authoritative documentation.
+        window_seconds: The rate window in seconds (``None`` for a static
+            threshold; ``0`` for a concurrency limit).
+        request_type: ``""`` (n/a) | ``read`` | ``write`` | ``any``.
+    """
+
+    name: str
+    value: int
+    kind: LimitKind = LimitKind.THRESHOLD
+    unit: str = "items"
+    scope: str = ""
+    note: str = ""
+    doc: str = ""
+    window_seconds: Optional[int] = None
+    request_type: str = ""
+
+    def __str__(self) -> str:
+        if self.window_seconds is not None:
+            window = f" / {self.window_seconds:,}s" if self.window_seconds else ""
+            return f"{self.value:,} {self.unit}{window}".strip()
+        if self.unit == "bytes":
+            return _human_bytes(self.value)
+        return f"{self.value:,} {self.unit}".strip()
+
+    def exceeds(self, value: int) -> bool:
+        """Whether ``value`` is over this limit."""
+        return value > self.value
+
+    @property
+    def is_rate(self) -> bool:
+        """Whether this is a rate quota (has a window)."""
+        return self.window_seconds is not None
+
+
+class LimitExceededError(ValueError):
+    """Raised when a value exceeds a service limit."""
+
+    def __init__(self, limit: Limit, value: int, *, context: str = "") -> None:
+        self.limit = limit
+        self.value = value
+        self.context = context
+        super().__init__(hint(limit, context=context, value=value))
+
+
+def exceeds(limit: Limit, value: int) -> bool:
+    """Whether ``value`` is over ``limit``."""
+    return limit.exceeds(value)
+
+
+def hint(limit: Limit, *, context: str = "", value: Optional[int] = None) -> str:
+    """An actionable message for a limit, optionally naming the offending value."""
+    where = f" for {context}" if context else ""
+    if value is None:
+        text = f"limit '{limit.name}'{where} is {limit}"
+    else:
+        text = f"{_format_value(limit, value)}{where} exceeds the limit '{limit.name}' ({limit})"
+    if limit.note:
+        text += f" — {limit.note}"
+    if limit.doc:
+        text += f" See {limit.doc}"
+    return text
+
+
+def _format_value(limit: Limit, value: int) -> str:
+    if limit.unit == "bytes":
+        return _human_bytes(value)
+    return f"{value:,} {limit.unit}".strip()
+
+
+def warn_if_exceeds(limit: Limit, value: int, *, context: str = "", stacklevel: int = 3) -> bool:
+    """Warn when ``value`` is over ``limit``. Returns whether it warned."""
+    if not limit.exceeds(value):
+        return False
+    warnings.warn(hint(limit, context=context, value=value), UserWarning, stacklevel=stacklevel)
+    return True
+
+
+def ensure_within(
+    limit: Limit,
+    value: int,
+    *,
+    context: str = "",
+    on_exceed: str = "raise",
+) -> None:
+    """Enforce ``limit`` for ``value`` — raise :class:`LimitExceededError` or warn.
+
+    Args:
+        on_exceed: ``"raise"`` (default) or ``"warn"``.
+    """
+    if on_exceed not in _ON_EXCEED:
+        raise ValueError(f"on_exceed must be one of {_ON_EXCEED}, got {on_exceed!r}")
+    if not limit.exceeds(value):
+        return
+    if on_exceed == "warn":
+        warn_if_exceeds(limit, value, context=context, stacklevel=4)
+    else:
+        raise LimitExceededError(limit, value, context=context)
+
+
+@dataclass(frozen=True)
+class LimitDecl:
+    """One declared limit — a :class:`Limit`, optionally bound to an argument.
+
+    ``arg`` names the numeric argument the limit is enforced against (``None``
+    for a documentation-only declaration); ``on_exceed`` / ``clamp`` decide the
+    enforcement behaviour.
+    """
+
+    limit: Limit
+    arg: Optional[str] = None
+    on_exceed: str = "warn"
+    clamp: bool = False
+
+
+def _append_doc(target: Callable[..., Any], decls: Tuple[LimitDecl, ...]) -> None:
+    lines: list[str] = []
+    for decl in decls:
+        bound = f" (<= {decl.limit})" if decl.arg else ""
+        lines.append(f"      {decl.limit.name}: {decl.limit}{bound}")
+    if lines:
+        target.__doc__ = (target.__doc__ or "") + "\n    Limits:\n" + "\n".join(lines)
+
+
+@overload
+def limit(
+    *limits: Limit,
+    arg: None = ...,
+    on_exceed: str = ...,
+    clamp: bool = ...,
+) -> Callable[[T], T]: ...
+
+
+@overload
+def limit(
+    *limits: Limit,
+    arg: str,
+    on_exceed: str = ...,
+    clamp: bool = ...,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def limit(
+    *limits: Limit,
+    arg: Optional[str] = None,
+    on_exceed: str = "warn",
+    clamp: bool = False,
+) -> Any:
+    """Declare service limits on a class, method or property (and optionally enforce one).
+
+    Metadata-only by default (like ``@odata`` / ``@require_permission``): the
+    declared :class:`Limit` values are stamped on the target and appended to its
+    docstring, then collected into ``_limit_meta`` / ``_class_limit_decls``.
+    Pass ``arg`` to also enforce that argument against the (single) limit — warn
+    by default, ``on_exceed="raise"`` to raise, or ``clamp=True`` to lower it
+    (methods only).
+
+    Usage::
+
+        @limit(Limits.FILE_UPLOAD)  # document
+        @limit(Limits.LIST_VIEW, arg="page_size")  # document + warn
+        @limit(Limits.BATCH_ITEMS, arg="items_per_batch", on_exceed="raise")
+        @limit(*IDENTITY_QUOTAS)  # on a class
+        class DirectoryObject(Entity): ...
+
+    Args:
+        *limits: The :class:`Limit` values to declare.
+        arg: Argument name to enforce (requires exactly one limit).
+        on_exceed: ``"warn"`` (default) or ``"raise"``.
+        clamp: Lower the argument to the limit instead of warning/raising.
+    """
+    if arg is not None and len(limits) != 1:
+        raise ValueError("arg= requires exactly one limit")
+    if on_exceed not in _ON_EXCEED:
+        raise ValueError(f"on_exceed must be one of {_ON_EXCEED}, got {on_exceed!r}")
+
+    decls = tuple(
+        LimitDecl(limit=item, arg=arg if index == 0 else None, on_exceed=on_exceed, clamp=clamp)
+        for index, item in enumerate(limits)
+    )
+
+    def decorator(func: Any) -> Any:
+        if isinstance(func, type):
+            if arg is not None:
+                raise ValueError("arg= cannot be used on a class")
+            _stamp(func, decls)
+            # ``__init_subclass__`` ran before this decorator (members already
+            # collected); merge the class-level declaration so subclasses inherit.
+            func._class_limit_decls = collect_class_limits(func)
+            register_catalog(func)
+            return func
+        if isinstance(func, property):
+            if arg is not None:
+                raise ValueError("arg= cannot be used on a property (properties take no arguments)")
+            _stamp(func.fget, decls)
+            return func
+
+        _stamp(func, decls)
+        if arg is None:
+            return func
+
+        arg_name: str = arg
+        signature = inspect.signature(func)
+        enforced = decls[0]
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = signature.bind_partial(*args, **kwargs)
+            value: Any = bound.arguments.get(arg_name)
+            if value is None or not enforced.limit.exceeds(value):
+                return func(*args, **kwargs)
+            if enforced.clamp:
+                bound.arguments[arg_name] = enforced.limit.value
+                return func(*bound.args, **bound.kwargs)
+            if enforced.on_exceed == "raise":
+                raise LimitExceededError(enforced.limit, value, context=func.__qualname__)
+            warn_if_exceeds(enforced.limit, value, context=func.__qualname__, stacklevel=2)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def _stamp(target: Any, decls: Tuple[LimitDecl, ...]) -> None:
+    setattr(target, _LIMIT_MARKER, decls)
+    _append_doc(target, decls)
+
+
+_limit = limit  # module alias (the ``bounded`` param name shadows ``limit`` below)
+
+
+def bounded(
+    arg: str,
+    limit: Limit,
+    *,
+    on_exceed: str = "warn",
+    clamp: bool = False,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Back-compat: ``@bounded(arg, limit)`` is ``@limit(limit, arg=arg)``."""
+    return _limit(limit, arg=arg, on_exceed=on_exceed, clamp=clamp)
+
+
+def collect_limit_meta(cls: type) -> dict[str, Tuple[LimitDecl, ...]]:
+    """Collect ``@limit`` declarations from a class's methods/properties.
+
+    Called from ``__init_subclass__`` (``ClientObject`` / ``ClientRuntimeContext``)
+    so a class carries its own limits — keyed by attribute/method name, inheriting
+    the base class's entries.
+    """
+    meta: dict[str, Tuple[LimitDecl, ...]] = dict(getattr(cls, "_limit_meta", {}))
+    for attr_name, attr in cls.__dict__.items():
+        target = attr.fget if isinstance(attr, property) else attr
+        decls = getattr(target, _LIMIT_MARKER, None)
+        if decls is not None:
+            meta[attr_name] = decls
+    return meta
+
+
+@runtime_checkable
+class LimitCatalog(Protocol):
+    """A source of :class:`Limit` values — anything with a ``catalog()`` method."""
+
+    def catalog(self) -> Iterable[Limit]: ...
+
+
+#: Registered limit sources, keyed by product (``"model"`` for ``@limit`` classes).
+_SOURCES: dict[str, list[Any]] = {}
+
+
+def _limits_from(source: Any) -> list[Limit]:
+    catalog_fn = getattr(source, "catalog", None)
+    if catalog_fn is not None:
+        return list(catalog_fn())
+    declared = getattr(source, "declared_limits", None)
+    if declared is not None:
+        return list(declared())
+    raise TypeError(f"{source!r} is not a Limit catalog (needs catalog() or declared_limits())")
+
+
+def register_catalog(*sources: Any, product: str = "model") -> None:
+    """Register limit sources — catalogs (``catalog()``) or classes (``declared_limits()``).
+
+    Products register their own catalogs at import time (e.g.
+    ``register_catalog(Limits, product="sharepoint")``); ``@limit`` on a class
+    registers that class under ``product="model"``.
+    """
+    bucket = _SOURCES.setdefault(product, [])
+    for source in sources:
+        if source not in bucket:
+            bucket.append(source)
+
+
+def catalog(product: Optional[str] = None) -> list[Limit]:
+    """All registered limits (optionally for one product), de-duplicated by identity."""
+    products = [product] if product is not None else list(_SOURCES)
+    seen: set[int] = set()
+    result: list[Limit] = []
+    for name in products:
+        for source in _SOURCES.get(name, ()):
+            for item in _limits_from(source):
+                if id(item) not in seen:
+                    seen.add(id(item))
+                    result.append(item)
+    return result
+
+
+def collect_class_limits(cls: type) -> Tuple[LimitDecl, ...]:
+    """The class-level ``@limit`` declarations of ``cls``.
+
+    Accumulates up the hierarchy: the base class's declarations plus the class's
+    own (a subclass is subject to both).
+    """
+    inherited = getattr(cls, "_class_limit_decls", ())
+    own = cls.__dict__.get(_LIMIT_MARKER)
+    if own is None:
+        return inherited
+    return (*inherited, *own)
+
+
+def limits_of(target: Any) -> Tuple[LimitDecl, ...]:
+    """The limits declared on a method/property, or a class's collected limits.
+
+    Args:
+        target: A callable (reads ``__limit_decls__``), a ``property``, or a
+            class (reads ``_limit_meta``).
+    """
+    if isinstance(target, type):
+        meta = getattr(target, "_limit_meta", {})
+        return tuple(decl for decls in meta.values() for decl in decls)
+    if isinstance(target, property):
+        target = target.fget
+    return tuple(getattr(target, _LIMIT_MARKER, ()))
+
+
+@dataclass
+class LimitReport:
+    """Diagnostic result of inspecting the limits declared on a target.
+
+    ``violations`` holds the ``(decl, value)`` pairs whose supplied value is over
+    the limit. This never raises and never touches the network.
+    """
+
+    target: str
+    decls: Tuple[LimitDecl, ...] = ()
+    violations: Tuple[Tuple[LimitDecl, int], ...] = field(default_factory=tuple)
+
+    @property
+    def limits(self) -> Tuple[Limit, ...]:
+        return tuple(decl.limit for decl in self.decls)
+
+    @property
+    def ok(self) -> bool:
+        """Whether all supplied values are within their limits."""
+        return not self.violations
+
+    def __str__(self) -> str:
+        head = f"{self.target}: {len(self.decls)} limit(s)"
+        if self.violations:
+            over = ", ".join(f"{decl.limit.name}={value:,}" for decl, value in self.violations)
+            return f"{head}; over: {over}"
+        return head
+
+
+def verify_limits(target: Any, **values: int) -> LimitReport:
+    """Inspect the limits declared on a method/property/class (diagnostic-only).
+
+    Keyword ``values`` are checked against the arg-bound declarations
+    (``@limit(..., arg=...)``); other limits are reported for reference.
+
+    Args:
+        target: A callable, ``property``, or class.
+        **values: Argument name -> value to check.
+
+    Returns:
+        A :class:`LimitReport`.
+    """
+    name = getattr(target, "__qualname__", None) or getattr(target, "__name__", str(target))
+    decls = limits_of(target)
+    violations = tuple(
+        (decl, values[decl.arg])
+        for decl in decls
+        if decl.arg is not None and decl.arg in values and decl.limit.exceeds(values[decl.arg])
+    )
+    return LimitReport(target=name, decls=decls, violations=violations)

office365/runtime/odata/request.py

@@ -20,19 +20,28 @@ from office365.runtime.queries.delete_entity import DeleteEntityQuery
 from office365.runtime.queries.function import FunctionQuery
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.runtime.queries.update_entity import UpdateEntityQuery
+from office365.runtime.transport.base import BaseTransport
 
 
 class ODataRequest(ClientRequest):
     """Handles OData protocol specific request/response processing for API calls."""
 
-    def __init__(self, base_url: str, json_format: ODataJsonFormat) -> None:
+    def __init__(
+        self,
+        base_url: str,
+        json_format: ODataJsonFormat,
+        transport: "BaseTransport | None" = None,
+    ) -> None:
         """
         Initialize a new OData request processor.
 
         Args:
+            base_url: The service base URL.
             json_format: The JSON format handler for OData serialization/deserialization
+            transport: Optional shared transport (e.g. one pooled ``Session`` for
+                parallel batch requests); defaults to a new ``RequestsTransport``.
         """
-        super().__init__()
+        super().__init__(transport=transport)
         self._base_url = base_url
         self._default_json_format = json_format
         self.beforeExecute += self._ensure_http_headers

office365/runtime/odata/type.py

@@ -22,6 +22,7 @@ _PRIMITIVE_TYPES = {
     "Edm.Duration": datetime.timedelta,
     "Edm.Date": datetime.date,
     "Edm.TimeOfDay": datetime.time,
+    "Edm.Time": datetime.time,  # OData v3 name for a time-of-day (kept after TimeOfDay for reverse lookup)
     "Edm.Json": dict,
     "Collection(SP.KeyValue)": dict,
     "Collection(Edm.Guid)": GuidCollection,

office365/runtime/odata/v3/batch_request.py

@@ -53,6 +53,7 @@ class ODataBatchV3Request(ODataRequest):
             query: The original batch query
         """
         for sub_qry, sub_resp in self._extract_response(response, query):
+            self._observe_throttle(sub_resp)
             sub_resp.raise_for_status()
             super().process_response(sub_resp, sub_qry)
 
@@ -77,7 +78,7 @@ class ODataBatchV3Request(ODataRequest):
             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
+        from office365.runtime.retry import TRANSIENT_STATUS_CODES, response_retry_after, retry, retry_after_delay
 
         state: dict = {"pending": query, "retry_after": None}
 
@@ -94,6 +95,7 @@ class ODataBatchV3Request(ODataRequest):
             failures: list[tuple[ClientQuery, Response]] = []
             retry_after: Optional[int] = None
             for sub_qry, sub_resp in self._extract_response(response, state["pending"]):
+                self._observe_throttle(sub_resp)
                 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)
@@ -113,7 +115,7 @@ class ODataBatchV3Request(ODataRequest):
                 max_retry=max_retry,
                 timeout_secs=base_delay,
                 jitter=jitter,
-                on_failure=lambda _attempt_num, _ex: state["retry_after"],
+                on_failure=lambda _attempt_num, ex: state["retry_after"] or retry_after_delay(ex),
             )
         except WholeBatchRejected as reject:
             self._split_and_retry(query, reject, max_retry, base_delay, jitter)

office365/runtime/odata/v4/batch_request.py

@@ -51,6 +51,7 @@ class ODataV4BatchRequest(ODataRequest):
             HTTPError: If any sub-request in the batch fails
         """
         for sub_qry, sub_resp in self._extract_response(response, query):
+            self._observe_throttle(sub_resp)
             sub_resp.raise_for_status()
             super().process_response(sub_resp, sub_qry)
 
@@ -76,7 +77,7 @@ class ODataV4BatchRequest(ODataRequest):
             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
+        from office365.runtime.retry import TRANSIENT_STATUS_CODES, response_retry_after, retry, retry_after_delay
 
         state: dict = {"pending": query, "retry_after": None}
 
@@ -93,6 +94,7 @@ class ODataV4BatchRequest(ODataRequest):
             failures: list[tuple[ClientQuery, Response]] = []
             retry_after: Optional[int] = None
             for sub_qry, sub_resp in self._extract_response(response, state["pending"]):
+                self._observe_throttle(sub_resp)
                 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)
@@ -103,7 +105,7 @@ class ODataV4BatchRequest(ODataRequest):
                 self.afterExecute(response)
                 return
             state["retry_after"] = retry_after or None
-            state["pending"] = BatchQuery(query.context, [qry for qry, _ in failures])
+            state["pending"] = BatchQuery(query.context, [qry for qry, _ in failures], sequential=query.sequential)
             raise ClientRequestException.from_response(failures[0][1])
 
         try:
@@ -112,7 +114,7 @@ class ODataV4BatchRequest(ODataRequest):
                 max_retry=max_retry,
                 timeout_secs=base_delay,
                 jitter=jitter,
-                on_failure=lambda _attempt_num, _ex: state["retry_after"],
+                on_failure=lambda _attempt_num, ex: state["retry_after"] or retry_after_delay(ex),
             )
         except WholeBatchRejected as reject:
             self._split_and_retry(query, reject, max_retry, base_delay, jitter)
@@ -134,7 +136,9 @@ class ODataV4BatchRequest(ODataRequest):
             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)
+            self.execute_query_with_retry(
+                BatchQuery(query.context, half, sequential=query.sequential), max_retry, base_delay, jitter
+            )
 
     @staticmethod
     def _extract_response(response: Response, query: BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]:
@@ -154,22 +158,33 @@ class ODataV4BatchRequest(ODataRequest):
             resp.headers = CaseInsensitiveDict(json_resp["headers"])
             resp._content = json.dumps(json_resp["body"]).encode("utf-8")
             qry_id = int(json_resp["id"])
-            qry = query.ordered_queries[qry_id]
+            # Ids are assigned in submission order (see ``_prepare_payload``), so
+            # map back with the same list — ``ordered_queries`` re-groups (non-GET
+            # first) and would attribute mixed batches to the wrong queries.
+            qry = query.queries[qry_id]
             yield qry, resp
 
     def _prepare_payload(self, query: BatchQuery) -> Dict[str, Any]:
         """Prepares the batch request payload.
 
+        With ``query.sequential`` the sub-requests are chained with ``dependsOn``
+        so Graph runs them in order (a failed dependency yields ``424``). Ids are
+        assigned in submission order — the same order :meth:`_extract_response`
+        maps responses back with.
+
         Args:
             query: The BatchQuery containing individual queries
 
         Returns:
             Dictionary containing the JSON batch request structure
         """
-        requests_json = []
+        requests_json: list[dict] = []
+        previous_id: Optional[str] = None
         for qry in query.queries:
             qry_id = str(len(requests_json))
-            requests_json.append(self._normalize_request(qry, qry_id))
+            depends_on = [previous_id] if (query.sequential and previous_id is not None) else None
+            requests_json.append(self._normalize_request(qry, qry_id, depends_on))
+            previous_id = qry_id
 
         return {"requests": requests_json}
 

office365/runtime/operations.py

@@ -49,6 +49,35 @@ class Progress(Generic[T_co]):
 ProgressCallback = Callable[[Progress[Any]], None]
 
 
+def emit_progress(
+    progress: Optional[ProgressCallback],
+    *,
+    done: int,
+    total: Optional[int] = None,
+    stage: str = "",
+    items: Optional[Sequence[Any]] = None,
+) -> None:
+    """Invoke a progress hook (if any) with a :class:`Progress` snapshot."""
+    if callable(progress):
+        progress(Progress(done=done, total=total, stage=stage, items=items))
+
+
+@dataclass
+class OperationStats:
+    """Common counters shared by bulk operations (imports, migrations).
+
+    The base carries only the fields every operation can report, so a consumer
+    that needs just totals accepts any specialization (``ImportStats``,
+    ``MigrationStats``) without a lossy conversion. Specializations add their own
+    extras (``chunks``/``duration``, ``bytes_transferred``).
+    """
+
+    total: int = 0
+    success: int = 0
+    skipped: int = 0
+    errors: int = 0
+
+
 class ProgressTracker:
     """Shared emitter that turns operation sub-steps into ``Progress`` snapshots.