ionq_core.pagination

  1# SPDX-FileCopyrightText: 2026 IonQ, Inc.
  2# SPDX-License-Identifier: Apache-2.0
  3
  4"""Pagination helpers for cursor-based IonQ API endpoints.
  5
  6The IonQ API returns paginated results with a ``next`` cursor. The helpers
  7in this module wrap the raw endpoint calls and automatically follow cursors,
  8yielding individual job objects.
  9
 10Example:
 11    ```python
 12    from ionq_core import IonQClient, iter_jobs
 13
 14    client = IonQClient()
 15    for job in iter_jobs(client, status="completed"):
 16        print(job.id)
 17    ```
 18"""
 19
 20from __future__ import annotations
 21
 22__all__ = ["aiter_jobs", "aiter_session_jobs", "iter_jobs", "iter_session_jobs"]
 23
 24import logging
 25from collections.abc import AsyncIterator, Callable, Iterator
 26from typing import TYPE_CHECKING, Any
 27
 28from .api.default import get_jobs, get_session_jobs
 29from .exceptions import IonQError
 30from .types import UNSET, Unset
 31
 32if TYPE_CHECKING:
 33    from .client import AuthenticatedClient
 34    from .models.base_job import BaseJob as Job
 35    from .models.job_status import JobStatus
 36
 37logger = logging.getLogger("ionq_core")
 38
 39
 40def _paginate(fetch: Callable[..., Any], label: str, *args: Any, **kwargs: Any) -> Iterator[Job]:
 41    kwargs["next_"] = UNSET
 42    while True:
 43        response = fetch(*args, **kwargs)
 44        if response is None:
 45            raise IonQError(f"Failed to fetch {label}")
 46        yield from response.jobs
 47        if response.next_ is None:
 48            return
 49        kwargs["next_"] = response.next_
 50        logger.debug("Fetching next page of %s (cursor=%s)", label, response.next_)
 51
 52
 53async def _apaginate(fetch: Callable[..., Any], label: str, *args: Any, **kwargs: Any) -> AsyncIterator[Job]:
 54    kwargs["next_"] = UNSET
 55    while True:
 56        response = await fetch(*args, **kwargs)
 57        if response is None:
 58            raise IonQError(f"Failed to fetch {label}")
 59        for job in response.jobs:
 60            yield job
 61        if response.next_ is None:
 62            return
 63        kwargs["next_"] = response.next_
 64        logger.debug("Fetching next page of %s (cursor=%s)", label, response.next_)
 65
 66
 67def iter_jobs(
 68    client: AuthenticatedClient,
 69    *,
 70    status: JobStatus | Unset = UNSET,
 71    target: str | Unset = UNSET,
 72    session_id: str | Unset = UNSET,
 73    submitter_id: str | Unset = UNSET,
 74    limit: int | Unset = UNSET,
 75) -> Iterator[Job]:
 76    """Iterate over all jobs, automatically following pagination cursors.
 77
 78    Args:
 79        client: An authenticated API client.
 80        status: Filter by job status (e.g. ``"completed"``, ``"failed"``).
 81        target: Filter by backend target name.
 82        session_id: Filter by session ID.
 83        submitter_id: Filter by submitter user ID.
 84        limit: Maximum number of jobs per page (server default applies
 85            if unset).
 86
 87    Yields:
 88        Individual job objects across all pages.
 89
 90    Raises:
 91        IonQError: If the API returns a ``None`` response.
 92    """
 93    return _paginate(
 94        get_jobs.sync,
 95        "jobs",
 96        client=client,
 97        status=status,
 98        target=target,
 99        session_id=session_id,
100        submitter_id=submitter_id,
101        limit=limit,
102    )
103
104
105def aiter_jobs(
106    client: AuthenticatedClient,
107    *,
108    status: JobStatus | Unset = UNSET,
109    target: str | Unset = UNSET,
110    session_id: str | Unset = UNSET,
111    submitter_id: str | Unset = UNSET,
112    limit: int | Unset = UNSET,
113) -> AsyncIterator[Job]:
114    """Async version of `iter_jobs`.
115
116    Args:
117        client: An authenticated API client.
118        status: Filter by job status.
119        target: Filter by backend target name.
120        session_id: Filter by session ID.
121        submitter_id: Filter by submitter user ID.
122        limit: Maximum number of jobs per page.
123
124    Yields:
125        Individual job objects across all pages.
126
127    Raises:
128        IonQError: If the API returns a ``None`` response.
129    """
130    return _apaginate(
131        get_jobs.asyncio,
132        "jobs",
133        client=client,
134        status=status,
135        target=target,
136        session_id=session_id,
137        submitter_id=submitter_id,
138        limit=limit,
139    )
140
141
142def iter_session_jobs(
143    client: AuthenticatedClient,
144    session_id: str,
145    *,
146    status: JobStatus | Unset = UNSET,
147    target: str | Unset = UNSET,
148    submitter_id: str | Unset = UNSET,
149    limit: int | Unset = UNSET,
150) -> Iterator[Job]:
151    """Iterate over all jobs in a specific session.
152
153    Like `iter_jobs`, but scoped to a single session.
154
155    Args:
156        client: An authenticated API client.
157        session_id: The session ID to list jobs for.
158        status: Filter by job status.
159        target: Filter by backend target name.
160        submitter_id: Filter by submitter user ID.
161        limit: Maximum number of jobs per page.
162
163    Yields:
164        Individual job objects across all pages.
165
166    Raises:
167        IonQError: If the API returns a ``None`` response.
168    """
169    return _paginate(
170        get_session_jobs.sync,
171        "session jobs",
172        session_id,
173        client=client,
174        status=status,
175        target=target,
176        submitter_id=submitter_id,
177        limit=limit,
178    )
179
180
181def aiter_session_jobs(
182    client: AuthenticatedClient,
183    session_id: str,
184    *,
185    status: JobStatus | Unset = UNSET,
186    target: str | Unset = UNSET,
187    submitter_id: str | Unset = UNSET,
188    limit: int | Unset = UNSET,
189) -> AsyncIterator[Job]:
190    """Async version of `iter_session_jobs`.
191
192    Args:
193        client: An authenticated API client.
194        session_id: The session ID to list jobs for.
195        status: Filter by job status.
196        target: Filter by backend target name.
197        submitter_id: Filter by submitter user ID.
198        limit: Maximum number of jobs per page.
199
200    Yields:
201        Individual job objects across all pages.
202
203    Raises:
204        IonQError: If the API returns a ``None`` response.
205    """
206    return _apaginate(
207        get_session_jobs.asyncio,
208        "session jobs",
209        session_id,
210        client=client,
211        status=status,
212        target=target,
213        submitter_id=submitter_id,
214        limit=limit,
215    )