Office365-REST-Python-Client 3.0.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/batch_util.py

@@ -0,0 +1,92 @@
+"""Batch request sizing utilities.
+
+Proactive chunking: batches are split by sub-request **count** and by estimated
+**payload bytes** so a batch never exceeds a service request-size limit.
+Reactive fallback: a whole-batch transport rejection (nothing was applied) is
+signalled with :class:`WholeBatchRejected`, which callers halve and retry.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional, Sequence
+
+from office365.runtime.client_request_exception import ClientRequestException
+
+# Batch-level HTTP statuses that indicate the whole request was rejected before
+# any sub-request ran (e.g. the body exceeds a request-size limit).
+WHOLE_BATCH_REJECT_CODES = frozenset({400, 413, 414, 431})
+
+_BATCH_OVERHEAD = 1024  # multipart/JSON envelope allowance per batch
+_PART_OVERHEAD = 256  # per-sub-request header/boundary allowance
+
+
+def estimate_query_bytes(query) -> int:
+    """Estimate the wire size of a batched sub-request without building a request.
+
+    Builds the URL from the query's resource path and serializes its payload
+    locally — no transport/auth side effects.
+    """
+    url = getattr(query, "url", "") or ""
+    size = len(str(url).encode("utf-8"))
+
+    payload = getattr(query, "parameters_type", None)
+    body = None
+    if payload is not None:
+        if isinstance(payload, dict):
+            body = json.dumps(payload, separators=(",", ":"))
+        elif isinstance(payload, (str, bytes)):
+            body = str(payload)
+        else:
+            try:
+                body = json.dumps(payload.to_json(None), separators=(",", ":"))
+            except Exception:
+                body = str(payload)
+        size += len(str(body).encode("utf-8"))
+
+    headers = getattr(query, "custom_headers", None) or {}
+    for k, v in headers.items():
+        size += len(str(k)) + len(str(v))
+    return size + _PART_OVERHEAD
+
+
+def partition_by_limits(
+    queries: Sequence,
+    max_items: Optional[int],
+    max_bytes: Optional[int],
+) -> list[list]:
+    """Split queries into batches respecting item and byte caps (order preserved).
+
+    A single oversized query still becomes its own one-item batch, so a request
+    rejected purely because of size is sent alone.
+    """
+    batches: list[list] = []
+    current: list = []
+    current_bytes = _BATCH_OVERHEAD
+    for query in queries:
+        if max_items is not None and len(current) >= max_items:
+            batches.append(current)
+            current, current_bytes = [], _BATCH_OVERHEAD
+        item_bytes = estimate_query_bytes(query)
+        if max_bytes is not None and current and current_bytes + item_bytes > max_bytes:
+            batches.append(current)
+            current, current_bytes = [], _BATCH_OVERHEAD
+        current.append(query)
+        current_bytes += item_bytes
+    if current:
+        batches.append(current)
+    return batches
+
+
+class WholeBatchRejected(ClientRequestException):
+    """Internal marker: the whole batch HTTP request was rejected.
+
+    Raised only for a transport-level rejection (before any sub-request was
+    applied); callers may safely halve the batch and retry.
+    """
+
+    def __init__(self, queries: list, cause: ClientRequestException) -> None:
+        super().__init__(str(cause))
+        self.queries = list(queries)
+        self.__cause__ = cause
+        self.response = getattr(cause, "response", None)

office365/runtime/odata/query_options.py

@@ -48,13 +48,23 @@ class QueryOptions:
         """Checks if any query options are set."""
         return not any(self.__dict__.values())
 
+    _ODATA_OPTIONS = ("select", "expand", "filter", "order_by", "top", "skip")
+
     def to_url(self) -> str:
         """Generates URL query string from current options.
 
+        Standard OData system query options are prefixed with ``$``; custom
+        query parameters are emitted verbatim (the caller controls the key,
+        e.g. ``token`` for OneDrive/SharePoint delta queries).
+
         Returns:
             URL-encoded query string (without leading ?)
         """
-        return "&".join([f"${key}={value}" for (key, value) in self])
+        parts = []
+        for key, value in self:
+            prefix = "$" if key in self._ODATA_OPTIONS else ""
+            parts.append(f"{prefix}{key}={value}")
+        return "&".join(parts)
 
     def __iter__(self) -> Iterator[Tuple[str, str]]:
         """Yields non-empty query options as key-value pairs."""
@@ -67,3 +77,18 @@ class QueryOptions:
                 yield from self.custom.items()
             else:
                 yield k, str(v)
+
+    def apply_to(self, target) -> None:
+        """Forward ``$select`` / ``$expand`` onto a collection-like target about to load.
+
+        Used by recursive scan helpers so the fluent ``.select(...)`` /
+        ``.expand(...)`` applied to their returned collection reaches every
+        request they issue (the scan reads the options at execution time).
+
+        Args:
+            target: A collection exposing ``select`` / ``expand`` (duck-typed).
+        """
+        if self.select:
+            target.select(list(self.select))
+        if self.expand:
+            target.expand(list(self.expand))

office365/runtime/odata/request.py

@@ -7,6 +7,7 @@ from requests import Response
 
 from office365.runtime.client_object import ClientObject
 from office365.runtime.client_request import ClientRequest
+from office365.runtime.client_request_exception import ClientRequestException
 from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value import ClientValue
 from office365.runtime.http.http_method import HttpMethod
@@ -19,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
@@ -77,7 +87,10 @@ class ODataRequest(ClientRequest):
         if isinstance(return_type, ClientObject):
             return_type.clear_state()
 
-        if response.headers.get("Content-Type", "").lower().split(";")[0] != "application/json":
+        content_type = response.headers.get("Content-Type", "").lower().split(";")[0]
+        is_raw_content = isinstance(query, FunctionQuery) and query.return_raw_content
+
+        if content_type != "application/json" or is_raw_content:
             if isinstance(return_type, ClientResult):
                 return_type.set_property("__value", response.content)
         else:
@@ -85,7 +98,10 @@ class ODataRequest(ClientRequest):
                 if isinstance(query, (ServiceOperationQuery, FunctionQuery)):
                     json_format.function = query.name
 
-            self.map_json(response.json(), return_type, json_format)
+            try:
+                self.map_json(response.json(), return_type, json_format)
+            except ValueError as e:
+                raise ClientRequestException(str(e), response=response) from e
 
     def map_json(
         self,
@@ -138,25 +154,29 @@ class ODataRequest(ClientRequest):
                     yield index, transformed if isinstance(item, dict) else item
             elif isinstance(json, dict):
                 for name, value in json.items():
-                    if isinstance(json_format, JsonLightFormat):
-                        is_valid = name != json_format.metadata_type and not (
-                            isinstance(value, dict) and "__deferred" in value
-                        )
-                    else:
-                        is_valid = "@odata" not in name
-
-                    if is_valid:
-                        transformed = None
-                        if isinstance(value, dict):
-                            transformed = {k: v for k, v in self._next_property(value, json_format)}
-                        yield name, transformed if isinstance(value, dict) else value
-                    elif name == "@odata.etag":
-                        yield "__etag", value
+                    yield from self._next_object_property(name, value, json_format)
             else:
                 yield "__value", json
         elif json is not None:
             yield "__value", json
 
+    def _next_object_property(self, name: str, value: Any, json_format: ODataJsonFormat) -> Iterator[Tuple[str, Any]]:
+        """Yields a single property from a JSON object according to the OData format."""
+        if isinstance(json_format, JsonLightFormat):
+            is_valid = name != json_format.metadata_type and not (isinstance(value, dict) and "__deferred" in value)
+        else:
+            is_valid = "@odata" not in name
+
+        if is_valid:
+            if isinstance(value, dict):
+                yield name, {k: v for k, v in self._next_property(value, json_format)}
+            else:
+                yield name, value
+        elif name == json_format.etag:
+            yield "__etag", value
+        elif name == json_format.metadata_type and isinstance(value, str):
+            yield "__odata_type", value
+
     def _build_payload(self, query: ClientQuery) -> Union[Dict[str, Any], List[Any], str, bytes]:
         """
         Normalizes OData request payload.