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

office365/runtime/converters/value.py

@@ -0,0 +1,186 @@
+"""Value-level conversion between stored values and their JSON representation.
+
+The shared conversion layer: ``serialize_value`` maps stored values to their JSON
+form (used by ``ClientObject``/``ClientValue``/``ClientValueCollection``
+``to_json``), and ``deserialize_value``/``declared_type`` map raw values to their
+declared type (used by ``set_property``). ``_add_type_metadata`` attaches the
+OData type marker.
+"""
+
+from __future__ import annotations
+
+import re
+import types
+import uuid
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Dict, Optional, Tuple, Union, get_args, get_origin, get_type_hints
+
+from office365.runtime.converters.scalars import parse_bool, parse_datetime, parse_enum, try_float, try_int
+from office365.runtime.odata.json_format import ODataJsonFormat
+from office365.runtime.odata.v3.json_light_format import JsonLightFormat
+
+_UNSET = object()
+_NoneType = type(None)
+
+_SCALAR_CONVERTERS = {
+    bool: parse_bool,
+    int: try_int,
+    float: try_float,
+    datetime: parse_datetime,
+}
+
+_declared_cache: Dict[Tuple[type, str], Any] = {}
+
+
+def serialize_value(value: Any, json_format: Optional[ODataJsonFormat] = None) -> Any:
+    """Convert a stored value to its JSON representation.
+
+    Handles ``ClientObject``/``ClientValue``/``ClientValueCollection`` (via their
+    ``to_json``), ``Enum`` -> value, ``datetime``/``date`` -> ISO 8601, ``bytes``
+    -> UTF-8, ``UUID`` -> str. Any other value (scalar, ``None``, ``dict``,
+    ``list``, ``ClientResult``) passes through unchanged.
+    """
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, uuid.UUID):
+        return str(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if hasattr(value, "to_json"):
+        return value.to_json(json_format)
+    return value
+
+
+def _add_type_metadata(
+    result: Dict[str, Any], json_format: Optional[ODataJsonFormat], entity_type_name: Optional[str]
+) -> None:
+    """Attach the OData type metadata marker when the format requests it."""
+    if json_format is not None and json_format.include_control_information and entity_type_name is not None:
+        if isinstance(json_format, JsonLightFormat):
+            result[json_format.metadata_type] = {"type": entity_type_name}
+        else:
+            result[json_format.metadata_type] = "#" + entity_type_name
+
+
+def to_snake_case(name: str) -> str:
+    """Convert a camelCase property name to its snake_case Python attribute."""
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def _unwrap_type(target: Any) -> Any:
+    """Strip Optional/Union wrappers from a type annotation."""
+    origin = get_origin(target)
+    if origin in (Union, getattr(types, "UnionType", None)):
+        args = [a for a in get_args(target) if a is not _NoneType]
+        return args[0] if len(args) == 1 else target
+    return target
+
+
+def declared_type(cls: type, name: str) -> Any:
+    """Resolve the declared (unwrapped) type of a property/field by its OData name.
+
+    Entities resolve the ``@odata``-mapped or snake_case getter's return
+    annotation; ``ClientValue`` dataclasses the field annotation. ``None`` when
+    unresolvable. Cached per ``(cls, name)``.
+    """
+    key = (cls, name)
+    if key in _declared_cache:
+        return _declared_cache[key]
+    declared = _resolve_declared_type(cls, name)
+    _declared_cache[key] = declared
+    return declared
+
+
+def _resolve_declared_type(cls: type, name: str) -> Any:
+    meta = getattr(cls, "_odata_meta", {}).get(name)
+    attr = meta.attr if meta is not None else to_snake_case(name)
+    member = getattr(cls, attr, None)
+    if member is not None:
+        target = member.fget if isinstance(member, property) else member
+        try:
+            declared = get_type_hints(target).get("return")
+        except Exception:
+            declared = None
+        if declared is not None:
+            return _unwrap_type(declared)
+    try:
+        declared = get_type_hints(cls).get(name)
+    except Exception:
+        declared = None
+    return _unwrap_type(declared) if declared is not None else None
+
+
+def is_client_value_type(target: Any) -> bool:
+    """Whether a type annotation represents a ``ClientValue`` (or generic ``ClientValueCollection``).
+
+    Uses the ``_is_client_value`` class marker so the conversion layer doesn't
+    import ``ClientValue`` (avoiding a cycle). ``get_type_hints`` returns
+    parametrized collections as a ``_GenericAlias``, so the origin is checked too.
+    """
+    cls = target if isinstance(target, type) else get_origin(target)
+    return isinstance(cls, type) and getattr(cls, "_is_client_value", False)
+
+
+def _client_value_origin(target: Any) -> type:
+    """Return the concrete class of a ClientValue type annotation."""
+    return target if isinstance(target, type) else get_origin(target)
+
+
+def deserialize_declared(value: Any, declared_type: Any) -> Any:
+    """Coerce a value to a declared scalar or enum type.
+
+    Returns ``_UNSET`` when the declared type isn't a supported scalar/enum, so
+    callers can fall back to their own handling.
+    """
+    converter = _SCALAR_CONVERTERS.get(declared_type)
+    if converter is not None:
+        return converter(value)
+    if isinstance(declared_type, type) and issubclass(declared_type, Enum):
+        return parse_enum(declared_type, value)
+    return _UNSET
+
+
+def deserialize_nested(base: Any, value: Any, persist_changes: bool) -> Any:
+    """Apply a raw list/dict onto a nested ``ClientValue``/``ClientObject``
+    (whose ``set_property`` maps list items by index and dict items by key),
+    returning the stored value. Scalar values are returned as-is.
+    """
+    if isinstance(value, list):
+        for i, p_v in enumerate(value):
+            base.set_property(i, p_v, persist_changes)
+    elif isinstance(value, dict):
+        for k, p_v in value.items():
+            base.set_property(k, p_v, persist_changes)
+    else:
+        return value
+    return base
+
+
+def deserialize_value(target_type: Any, value: Any, current: Any, persist_changes: bool) -> Any:
+    """Coerce a raw value for storage by its declared type, falling back to the current instance.
+
+    Declared scalars/enums go through ``deserialize_declared``; declared
+    ``ClientValue``/``ClientValueCollection`` (including generic aliases) are
+    populated via ``deserialize_nested``. Otherwise the value is coerced against
+    the current instance (a nested ``ClientObject``/``ClientValue``, ``datetime``,
+    ``Enum``) or passed through raw.
+    """
+    if target_type is not None and value is not None:
+        coerced = deserialize_declared(value, target_type)
+        if coerced is not _UNSET:
+            return coerced
+        if is_client_value_type(target_type):
+            origin = _client_value_origin(target_type)
+            if not isinstance(current, origin):
+                current = origin()
+            return deserialize_nested(current, value, persist_changes)
+    if hasattr(current, "set_property") and not isinstance(current, (datetime, Enum)):
+        return deserialize_nested(current, value, persist_changes)
+    if isinstance(current, datetime):
+        return parse_datetime(value)
+    if isinstance(current, Enum):
+        return current if value is None else parse_enum(type(current), value)
+    return value

office365/runtime/decorators.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import warnings
+from functools import wraps
+
+
+def deprecated(reason: str, version: str = "next"):
+    """Mark functions/methods as deprecated with a warning.
+
+    Args:
+        reason: Explanation why this is deprecated
+        version: Version when this will be removed
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__} is deprecated and will be removed in v{version}. {reason}",
+                category=FutureWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

office365/runtime/http/mime.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import mimetypes
+
+
+def get_mime_type(file_name: str) -> tuple[str | None, str | None]:
+    """Guess the MIME type and encoding for a filename.
+
+    Returns:
+        Tuple of (type, encoding) where either may be None
+    """
+    return mimetypes.guess_type(file_name)

office365/runtime/http/throttling.py

@@ -0,0 +1,205 @@
+"""Parsing and reacting to throttling / health signals on responses.
+
+SharePoint Online reports server load via ``X-SharePointHealthScore`` on every
+response and ``Retry-After`` on throttled (429/503) responses. Per the current
+Microsoft guidance it does **not** return IETF ``RateLimit-*`` headers — those
+are parsed defensively here in case a proxy or other source provides them.
+
+Two ways to use it:
+
+- Attach :func:`rate_limit_hook` per query (``after_execute(..., include_response=True)``)
+  or to the request event handler for every response;
+- Wrap a workload in :func:`throttle_guard` for a scoped, self-removing guard
+  that hides the event plumbing entirely.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import astuple, dataclass
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional
+
+from requests import Response
+
+if TYPE_CHECKING:
+    from office365.runtime.client_runtime_context import ClientRuntimeContext
+
+
+@dataclass(frozen=True)
+class ThrottleLimits:
+    """Throttling state reported by the server on a successful response.
+
+    Attributes:
+        limit: Maximum requests permitted in the current window.
+        remaining: Requests still permitted before throttling kicks in.
+        reset: Seconds until the quota window resets.
+        retry_after: Seconds the server asks us to wait (``Retry-After``).
+        health_score: SharePoint health score (0-100), if reported.
+    """
+
+    limit: Optional[int] = None
+    remaining: Optional[int] = None
+    reset: Optional[int] = None
+    retry_after: Optional[int] = None
+    health_score: Optional[int] = None
+
+
+def parse_throttling(response: Response) -> Optional[ThrottleLimits]:
+    """Parse throttling / health headers from a response into a ``ThrottleLimits``.
+
+    Returns ``None`` when the response carries none of the tracked headers
+    (e.g. a Microsoft Graph response), so hooks can stay silent for other APIs.
+
+    Args:
+        response: The raw HTTP response.
+
+    Returns:
+        ThrottleLimits, or None when no tracked headers are present.
+    """
+    limits = ThrottleLimits(
+        limit=_to_int(response.headers.get("RateLimit-Limit")),
+        remaining=_to_int(response.headers.get("RateLimit-Remaining")),
+        reset=_to_int(response.headers.get("RateLimit-Reset")),
+        retry_after=_to_int(response.headers.get("Retry-After")),
+        health_score=_to_int(response.headers.get("X-SharePointHealthScore")),
+    )
+    if any(value is not None for value in astuple(limits)):
+        return limits
+    return None
+
+
+def rate_limit_hook(callback: Optional[Callable[[ThrottleLimits], None]] = None) -> Callable[[Response], None]:
+    """Return an after-execute hook that reports parsed throttling / health state.
+
+    The returned hook is compatible with ``after_execute`` (it expects the raw
+    ``Response``). It fires ``callback`` only when the response carries any of
+    the tracked headers — silent otherwise.
+
+    Usage:
+        >>> from office365.runtime.http.throttling import rate_limit_hook
+        >>> items.get().after_execute(rate_limit_hook(my_callback), include_response=True).execute_query()
+    """
+
+    def _hook(response: Response) -> None:
+        limits = parse_throttling(response)
+        if limits is not None and callable(callback):
+            callback(limits)
+
+    return _hook
+
+
+@contextmanager
+def throttle_guard(
+    context: "ClientRuntimeContext",
+    on_limits: Optional[Callable[[ThrottleLimits], None]] = None,
+) -> Iterator[None]:
+    """Monitor throttling / health signals on every response within a scope.
+
+    Attaches :func:`rate_limit_hook` to the request's ``afterExecute`` event
+    handler on enter and removes it on exit, so the guard applies to every query
+    executed inside the ``with`` block — no ``include_response`` plumbing needed.
+
+    Args:
+        context: The client context to monitor.
+        on_limits: Optional callback invoked with parsed state per response
+          (only when any of the tracked headers are present).
+
+    Usage:
+        >>> from office365.runtime.http.throttling import throttle_guard, ThrottleLimits
+        >>> def pace(limits: ThrottleLimits) -> None:
+        ...     if limits.remaining is not None and limits.remaining < 10:
+        ...         time.sleep(limits.reset or 1)
+        >>> with throttle_guard(ctx, on_limits=pace):
+        ...     ctx.execute_query()
+    """
+    handler = context.pending_request().afterExecute
+    hook = rate_limit_hook(on_limits)
+    handler += hook
+    try:
+        yield
+    finally:
+        handler -= hook
+
+
+def _to_int(value: Any) -> Optional[int]:
+    """Parse a header value into an int, returning None when absent/invalid."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class RateLimiter:
+    """Thread-safe gate shared across workers so parallel requests pace as a group.
+
+    Unlike :func:`throttle_guard` (reactive, per-context) and the per-request
+    backoff in ``retry.py``, this limiter coordinates a *fleet* of clones/workers:
+    before any request is sent it blocks until the group gate is open, and when
+    any worker observes throttling it pauses the whole group.
+
+    Opt-in — attach it to a context (or a clone) with :meth:`bind`; the existing
+    per-request retry remains as the safety net.
+    """
+
+    _SLEEP_GRANULARITY = 0.05
+
+    def __init__(self, health_threshold: int = 80, min_interval: float = 0.0) -> None:
+        self._lock = threading.RLock()
+        self._next_available_at = 0.0
+        self._health_threshold = health_threshold
+        self._min_interval = min_interval
+
+    def acquire(self) -> None:
+        """Block the calling thread until the group gate opens.
+
+        Called before a request is sent; safe to invoke from many threads.
+        """
+        while True:
+            with self._lock:
+                wait = self._next_available_at - time.monotonic()
+            if wait <= 0:
+                return
+            time.sleep(min(wait, self._SLEEP_GRANULARITY))
+
+    def observe(self, response: Optional[Response]) -> None:
+        """Record throttling signals and pause the group when the server asks.
+
+        A throttled response (``Retry-After``) gates the fleet for that long;
+        a high ``X-SharePointHealthScore`` applies a short, scaled pace so the
+        group eases off as the farm heats up.
+        """
+        if response is None:
+            return
+        limits = parse_throttling(response)
+        if limits is None:
+            return
+        now = time.monotonic()
+        with self._lock:
+            if limits.retry_after is not None and limits.retry_after > 0:
+                self._next_available_at = max(self._next_available_at, now + limits.retry_after)
+            if limits.health_score is not None and limits.health_score >= self._health_threshold:
+                pace = (limits.health_score - self._health_threshold) / 20.0
+                self._next_available_at = max(self._next_available_at, now + max(pace, self._min_interval))
+
+    def bind(self, context: "ClientRuntimeContext") -> "RateLimiter":
+        """Attach this limiter to a context (or ``clone``) — every request paces as a group.
+
+        Health signals are read on successful responses (``afterExecute``);
+        throttled responses (429/503) raise before ``afterExecute``, so their
+        ``Retry-After`` is read via ``onError`` instead.
+
+        Args:
+            context: The client context to monitor and gate.
+        """
+        request = context.pending_request()
+        request.beforeExecute += lambda _: self.acquire()
+        request.afterExecute += lambda response: self.observe(response)
+        request.onError += lambda ex: self.observe(getattr(ex, "response", None))
+        return self
+
+    def reset(self) -> None:
+        """Clear the current gate (used by tests / recovery)."""
+        with self._lock:
+            self._next_available_at = 0.0

office365/runtime/http/url.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlparse
+
+
+def is_absolute_url(url: str) -> bool:
+    """Determine if a URL is absolute (contains network location)."""
+    return bool(urlparse(url).netloc)
+
+
+def get_absolute_url(url: str) -> str:
+    """Extract the base URL (scheme+netloc) from a full URL.
+
+    Example:
+        >>> get_absolute_url("https://example.com/path?query=1")
+        'https://example.com'
+    """
+    path = urlparse(url).path
+    return url.replace(path, "")
+
+
+def parse_query_param(url: str, key: str) -> str:
+    """Extract the first value of a query string parameter.
+
+    Args:
+        url: URL containing query string
+        key: Query parameter key to look up
+
+    Returns:
+        First value for the specified key
+
+    Raises:
+        KeyError: If parameter not found
+    """
+    parsed_url = urlparse(url)
+    return parse_qs(parsed_url.query)[key][0]

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
@@ -77,7 +78,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 +89,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 +145,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.