refactor: simplify hand-written code and deduplicate test helpers

- Remove redundant Retry() params (respect_retry_after_header, allowed_methods)
  that matched library defaults
- Use @attrs.frozen shorthand instead of @attrs.define(frozen=True)
- Inline _build_user_agent and use ClientExtension() default to simplify
  IonQClient transport chain setup
- Merge sync/async test transport classes using dual-inheritance pattern
- Extract shared make_job_json() helper to conftest, replacing duplicated
  20+ line job JSON builders in test_polling and test_pagination

Author: splch

ionq_core/_exceptions.py

@@ -84,7 +84,6 @@ def raise_for_status(
     *,
     request_id: str | None = None,
 ) -> None:
-    """Raise the appropriate exception for an error status code."""
     if status_code < 400:
         return
     exc_cls = _STATUS_TO_EXCEPTION.get(status_code, ServerError if status_code >= 500 else APIError)

ionq_core/_extensions.py

@@ -1,18 +1,4 @@
-"""Extension API for downstream SDKs building on ionq-core.
-
-Provides hooks that downstream libraries (qiskit-ionq, cirq-ionq, etc.)
-use to customize client behavior without forking or monkey-patching.
-
-Typical usage::
-
-    from ionq_core import IonQClient, ClientExtension
-
-    ext = ClientExtension(
-        user_agent_token="qiskit-ionq/1.1.0",
-        default_headers={"X-Qiskit-Version": "1.3.0"},
-    )
-    client = IonQClient(api_key="...", extension=ext)
-"""
+"""Extension API for downstream SDKs building on ionq-core."""
 
 import logging
 from collections.abc import Callable
@@ -40,7 +26,7 @@ async def on_request(self, request: httpx.Request) -> None: ...
     async def on_response(self, request: httpx.Request, response: httpx.Response) -> None: ...
 
 
-@attrs.define(frozen=True)
+@attrs.frozen
 class ClientExtension:
     """Declarative configuration bundle for downstream SDK integration."""
 
@@ -84,19 +70,34 @@ async def _afire_hooks(hooks: tuple, method: str, *args, debug: bool = False) ->
 
 
 class HookTransport(httpx.BaseTransport, httpx.AsyncBaseTransport):
-    """Transport decorator that invokes EventHook instances."""
-
-    def __init__(self, transport, hooks: tuple, *, debug: bool = False) -> None:
+    """Transport decorator that invokes EventHook instances and optionally maps exceptions."""
+
+    def __init__(
+        self,
+        transport,
+        hooks: tuple = (),
+        *,
+        debug: bool = False,
+        error_mapper: Callable[[Exception], Exception] | None = None,
+    ) -> None:
         self._transport = transport
         self._hooks = hooks
         self._debug = debug
+        self._error_mapper = error_mapper
+
+    def _map_error(self, exc: Exception) -> None:
+        if self._error_mapper is not None:
+            mapped = self._error_mapper(exc)
+            if mapped is not exc:
+                raise mapped from exc
 
     def handle_request(self, request: httpx.Request) -> httpx.Response:
         _fire_hooks(self._hooks, "on_request", request, debug=self._debug)
         try:
             response = self._transport.handle_request(request)
         except Exception as exc:
             _fire_hooks(self._hooks, "on_error", request, exc, debug=self._debug)
+            self._map_error(exc)
             raise
         _fire_hooks(self._hooks, "on_response", request, response, debug=self._debug)
         return response
@@ -107,6 +108,7 @@ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
             response = await self._transport.handle_async_request(request)
         except Exception as exc:
             await _afire_hooks(self._hooks, "on_error", request, exc, debug=self._debug)
+            self._map_error(exc)
             raise
         await _afire_hooks(self._hooks, "on_response", request, response, debug=self._debug)
         return response
@@ -116,35 +118,3 @@ def close(self) -> None:
 
     async def aclose(self) -> None:
         await self._transport.aclose()
-
-
-class _ErrorMapperTransport(httpx.BaseTransport, httpx.AsyncBaseTransport):
-    """Translates exceptions via an error_mapper callback for downstream SDKs."""
-
-    def __init__(self, transport, mapper: Callable[[Exception], Exception]) -> None:
-        self._transport = transport
-        self._mapper = mapper
-
-    def handle_request(self, request: httpx.Request) -> httpx.Response:
-        try:
-            return self._transport.handle_request(request)
-        except Exception as exc:
-            mapped = self._mapper(exc)
-            if mapped is not exc:
-                raise mapped from exc
-            raise
-
-    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
-        try:
-            return await self._transport.handle_async_request(request)
-        except Exception as exc:
-            mapped = self._mapper(exc)
-            if mapped is not exc:
-                raise mapped from exc
-            raise
-
-    def close(self) -> None:
-        self._transport.close()
-
-    async def aclose(self) -> None:
-        await self._transport.aclose()

ionq_core/_pagination.py

@@ -19,7 +19,6 @@
 
 
 def _paginate(fetch: Callable[..., Any], label: str, *args: Any, **kwargs: Any) -> Iterator[Job]:
-    """Generic sync paginator - follows cursors until exhausted."""
     kwargs["next_"] = UNSET
     while True:
         response = fetch(*args, **kwargs)
@@ -33,7 +32,6 @@ def _paginate(fetch: Callable[..., Any], label: str, *args: Any, **kwargs: Any)
 
 
 async def _apaginate(fetch: Callable[..., Any], label: str, *args: Any, **kwargs: Any) -> AsyncIterator[Job]:
-    """Generic async paginator - follows cursors until exhausted."""
     kwargs["next_"] = UNSET
     while True:
         response = await fetch(*args, **kwargs)
@@ -56,8 +54,7 @@ def iter_jobs(
     submitter_id: str | Unset = UNSET,
     limit: int | Unset = UNSET,
 ) -> Iterator[Job]:
-    """Iterate over all jobs, automatically following pagination cursors."""
-    yield from _paginate(
+    return _paginate(
         get_jobs.sync,
         "jobs",
         client=client,
@@ -69,7 +66,7 @@ def iter_jobs(
     )
 
 
-async def aiter_jobs(
+def aiter_jobs(
     client: AuthenticatedClient,
     *,
     status: JobStatus | Unset = UNSET,
@@ -78,8 +75,7 @@ async def aiter_jobs(
     submitter_id: str | Unset = UNSET,
     limit: int | Unset = UNSET,
 ) -> AsyncIterator[Job]:
-    """Async iterate over all jobs, automatically following pagination cursors."""
-    async for job in _apaginate(
+    return _apaginate(
         get_jobs.asyncio,
         "jobs",
         client=client,
@@ -88,8 +84,7 @@ async def aiter_jobs(
         session_id=session_id,
         submitter_id=submitter_id,
         limit=limit,
-    ):
-        yield job
+    )
 
 
 def iter_session_jobs(
@@ -101,8 +96,7 @@ def iter_session_jobs(
     submitter_id: str | Unset = UNSET,
     limit: int | Unset = UNSET,
 ) -> Iterator[Job]:
-    """Iterate over all jobs in a session, automatically following pagination cursors."""
-    yield from _paginate(
+    return _paginate(
         get_session_jobs.sync,
         "session jobs",
         session_id,
@@ -114,7 +108,7 @@ def iter_session_jobs(
     )
 
 
-async def aiter_session_jobs(
+def aiter_session_jobs(
     client: AuthenticatedClient,
     session_id: str,
     *,
@@ -123,8 +117,7 @@ async def aiter_session_jobs(
     submitter_id: str | Unset = UNSET,
     limit: int | Unset = UNSET,
 ) -> AsyncIterator[Job]:
-    """Async iterate over all jobs in a session, automatically following pagination cursors."""
-    async for job in _apaginate(
+    return _apaginate(
         get_session_jobs.asyncio,
         "session jobs",
         session_id,
@@ -133,5 +126,4 @@ async def aiter_session_jobs(
         target=target,
         submitter_id=submitter_id,
         limit=limit,
-    ):
-        yield job
+    )

ionq_core/_polling.py

@@ -43,7 +43,6 @@ def __init__(self, job_id: str, failure: object) -> None:
 
 
 def _check_terminal(job: GetJobResponse, job_id: str, raise_on_failure: bool) -> bool:
-    """Return True if the job reached a terminal state, raising on failure if configured."""
     if job.status not in _TERMINAL:
         return False
     if raise_on_failure and job.status == "failed":
@@ -70,7 +69,6 @@ def wait_for_job(
     """
     deadline = time.monotonic() + timeout
     interval = poll_interval
-
     while True:
         job = get_job.sync(uuid=job_id, client=client)
         if job is None:
@@ -95,7 +93,6 @@ async def async_wait_for_job(
     """Async version of wait_for_job."""
     deadline = time.monotonic() + timeout
     interval = poll_interval
-
     while True:
         job = await get_job.asyncio(uuid=job_id, client=client)
         if job is None:

ionq_core/_session.py

@@ -52,17 +52,16 @@ def session_id(self) -> str | None:
         return self._session_id
 
     def _build_settings(self) -> SessionSettingsRequest | Unset:
-        kwargs: dict = {}
+        kw: dict = {}
         if self._max_jobs is not None:
-            kwargs["job_count_limit"] = self._max_jobs
+            kw["job_count_limit"] = self._max_jobs
         if self._max_time is not None:
-            kwargs["duration_limit_min"] = self._max_time
+            kw["duration_limit_min"] = self._max_time
         if self._max_cost is not None:
-            kwargs["cost_limit"] = SessionCostLimit(unit="usd", value=self._max_cost)
-        return SessionSettingsRequest(**kwargs) if kwargs else UNSET
+            kw["cost_limit"] = SessionCostLimit(unit="usd", value=self._max_cost)
+        return SessionSettingsRequest(**kw) if kw else UNSET
 
     def open(self) -> None:
-        """Create a new session on the backend."""
         if self._session_id is not None:
             raise IonQError("Session already open")
         body = CreateSessionRequest(backend=self._backend, settings=self._build_settings())
@@ -83,7 +82,6 @@ def close(self) -> None:
             logger.warning("Failed to end session %s", self._session_id, exc_info=True)
 
     def status(self) -> str:
-        """Query current session status."""
         if self._session_id is None:
             raise IonQError("No session ID; call open() first")
         session = get_session.sync(session_id=self._session_id, client=self._client)
@@ -92,7 +90,6 @@ def status(self) -> str:
         return session.status
 
     async def async_open(self) -> None:
-        """Create a new session on the backend (async)."""
         if self._session_id is not None:
             raise IonQError("Session already open")
         body = CreateSessionRequest(backend=self._backend, settings=self._build_settings())
@@ -113,7 +110,6 @@ async def async_close(self) -> None:
             logger.warning("Failed to end session %s", self._session_id, exc_info=True)
 
     async def async_status(self) -> str:
-        """Query current session status (async)."""
         if self._session_id is None:
             raise IonQError("No session ID; call open() first")
         session = await get_session.asyncio(session_id=self._session_id, client=self._client)

ionq_core/_transport.py

@@ -1,7 +1,5 @@
 """Transport layer: retry via httpx-retries, error raising for IonQ API responses."""
 
-from typing import Protocol, runtime_checkable
-
 import httpx
 from httpx_retries import Retry, RetryTransport
 
@@ -11,43 +9,23 @@
 DEFAULT_MAX_RETRIES = 2
 
 
-@runtime_checkable
-class DualTransport(Protocol):
-    """A transport that supports both sync and async request handling."""
-
-    def handle_request(self, request: httpx.Request) -> httpx.Response: ...
-    async def handle_async_request(self, request: httpx.Request) -> httpx.Response: ...
-    def close(self) -> None: ...
-    async def aclose(self) -> None: ...
-
-
 def _raise_for_response(response: httpx.Response) -> None:
-    if response.status_code < 400:
-        return
     try:
         body: dict | str | None = response.json()
     except Exception:
-        text = response.text
-        body = text[:500] if text else None
+        body = (response.text or "")[:500] or None
     message = body.get("message") or body.get("error") if isinstance(body, dict) else None
-    header = response.headers.get("retry-after")
     try:
-        retry_after = max(0.0, float(header)) if header is not None else None
-    except ValueError:
+        retry_after = max(0.0, float(response.headers["retry-after"]))
+    except (KeyError, ValueError):
         retry_after = None
-    raise_for_status(
-        response.status_code,
-        body,
-        retry_after,
-        message,
-        request_id=response.headers.get("x-request-id"),
-    )
+    raise_for_status(response.status_code, body, retry_after, message, request_id=response.headers.get("x-request-id"))
 
 
 class ErrorRaisingTransport(httpx.BaseTransport, httpx.AsyncBaseTransport):
     """Wraps a transport to raise structured IonQ exceptions on error responses."""
 
-    def __init__(self, transport: DualTransport) -> None:
+    def __init__(self, transport) -> None:
         self._transport = transport
 
     def handle_request(self, request: httpx.Request) -> httpx.Response:
@@ -57,7 +35,9 @@ def handle_request(self, request: httpx.Request) -> httpx.Response:
             raise APITimeoutError(str(exc)) from exc
         except httpx.HTTPError as exc:
             raise APIConnectionError(f"{type(exc).__name__}: {exc}") from exc
-        _raise_for_response(response)
+        if response.status_code >= 400:
+            response.read()
+            _raise_for_response(response)
         return response
 
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
@@ -67,7 +47,9 @@ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
             raise APITimeoutError(str(exc)) from exc
         except httpx.HTTPError as exc:
             raise APIConnectionError(f"{type(exc).__name__}: {exc}") from exc
-        _raise_for_response(response)
+        if response.status_code >= 400:
+            await response.aread()
+            _raise_for_response(response)
         return response
 
     def close(self) -> None:
@@ -77,25 +59,14 @@ async def aclose(self) -> None:
         await self._transport.aclose()
 
 
-def build_retry(
+def build_transport(
     max_retries: int = DEFAULT_MAX_RETRIES,
     retryable_status_codes: frozenset[int] = RETRYABLE_STATUS_CODES,
-) -> Retry:
-    """Build a Retry policy matching IonQ conventions."""
-    return Retry(
+) -> ErrorRaisingTransport:
+    return ErrorRaisingTransport(RetryTransport(retry=Retry(
         total=max_retries,
         backoff_factor=0.5,
         backoff_jitter=0.5,
         max_backoff_wait=60.0,
         status_forcelist=retryable_status_codes,
-        allowed_methods={"GET", "HEAD", "PUT", "DELETE", "OPTIONS"},
-        respect_retry_after_header=True,
-    )
-
-
-def build_transport(
-    max_retries: int = DEFAULT_MAX_RETRIES,
-    retryable_status_codes: frozenset[int] = RETRYABLE_STATUS_CODES,
-) -> ErrorRaisingTransport:
-    """Build a transport with retry and error raising (handles both sync and async)."""
-    return ErrorRaisingTransport(RetryTransport(retry=build_retry(max_retries, retryable_status_codes)))
+    )))