Odata Paginator

OData v4 cursor-pagination helpers (@odata.nextLink / @odata.deltaLink).

Generic OData v4 infrastructure — not specific to any one API. Microsoft Graph is the first consumer in this SDK, but the same @odata.nextLink/@odata.deltaLink convention is used by other OData v4 services (e.g. SharePoint REST, Dynamics 365).

scamander.api.odata_paginator.fetch_all_odata_pages(session: OAuth2Session, url: str, params: dict | None = None, timeout_secs: int = 120, max_size_mb: float = 5.0) → tuple[list[dict], str | None]

Follow @odata.nextLink until exhausted, collecting every page’s value array.

Query parameters are only sent on the first request — every subsequent request uses the full, self-describing @odata.nextLink URL returned by the previous page, exactly as the OData v4 spec requires.

Parameters:

  • session – Authenticated OAuth2Session.

  • url – Full URL of the first page (e.g. a resource collection or a resumed @odata.deltaLink).

  • params – Query parameters for the first request only (e.g. $select, $filter, $expand). Ignored on subsequent pages, since @odata.nextLink already encodes them. Defaults to None.

  • timeout_secs – Request timeout per page in seconds. Defaults to 120.

  • max_size_mb – Maximum allowed response body per page in MB. Defaults to 5.

Returns:

the flat list of records across all pages, and the final page’s @odata.deltaLink (present only on delta-query endpoints once fully synced), or None when the response never carries one.

Return type:

A (records, delta_link) tuple

Veroorzaakt:

  • requests.HTTPError – On a non-2xx response.

  • RuntimeError – When a response body exceeds max_size_mb.

  • ValueError – When a response JSON has no value array.

Example:

from scamander.api import OAuth2Session, fetch_all_odata_pages

session = OAuth2Session(
    token_url="https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token",
    client_id=client_id,
    client_secret=client_secret,
    scope="https://graph.microsoft.com/.default",
)
records, delta_link = fetch_all_odata_pages(
    session,
    "https://graph.microsoft.com/v1.0/users/delta",
    params={"$select": "id,displayName,mail"},
)