ionq_core

58class APIConnectionError(IonQError):
59    """Raised when a connection to the IonQ API cannot be established.
60
61    This covers DNS resolution failures, refused connections, and other
62    network-level errors. The original ``httpx`` exception is chained
63    via ``__cause__``.
64    """

 75class APIError(IonQError):
 76    """Raised when the IonQ API returns an HTTP error response (4xx or 5xx).
 77
 78    Attributes:
 79        status_code: The HTTP status code.
 80        body: The parsed response body (``dict`` if JSON, ``str`` otherwise,
 81            or ``None`` if the body could not be read).
 82        message: A human-readable error message extracted from the response,
 83            or a default ``"HTTP <status>"`` string.
 84        request_id: The ``x-request-id`` header from the response, useful for
 85            contacting IonQ support about a specific request.
 86    """
 87
 88    def __init__(
 89        self,
 90        status_code: int,
 91        body: dict | str | None = None,
 92        message: str | None = None,
 93        *,
 94        request_id: str | None = None,
 95    ) -> None:
 96        self.status_code = status_code
 97        self.body = body
 98        self.request_id = request_id
 99        self.message = message or f"HTTP {status_code}"
100        super().__init__(self.message)

67class APITimeoutError(APIConnectionError):
68    """Raised when a request to the IonQ API times out.
69
70    Inherits from `APIConnectionError` so that catching connection errors
71    also catches timeouts.
72    """

76@runtime_checkable
77class AsyncEventHook(Protocol):
78    """Async counterpart of `EventHook` for the async client path.
79
80    Implement this protocol and pass instances via
81    `ClientExtension.async_event_hooks`.
82    """
83
84    async def on_request(self, request: httpx.Request) -> None:
85        """Called after the request is built but before it is sent.
86
87        Args:
88            request: The outgoing HTTP request.
89        """
90        ...
91
92    async def on_response(self, request: httpx.Request, response: httpx.Response) -> None:
93        """Called after a response is received.
94
95        Args:
96            request: The original HTTP request.
97            response: The HTTP response.
98        """
99        ...

142@define
143class AuthenticatedClient:
144    """A Client which has been authenticated for use on secured endpoints
145
146    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
147
148        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
149
150        ``cookies``: A dictionary of cookies to be sent with every request
151
152        ``headers``: A dictionary of headers to be sent with every request
153
154        ``timeout``: The maximum amount of a time a request can take. API functions will raise
155        httpx.TimeoutException if this is exceeded.
156
157        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
158        but can be set to False for testing purposes.
159
160        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
161
162        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
163
164
165    Attributes:
166        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
167            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
168            argument to the constructor.
169        token: The token to use for authentication
170        prefix: The prefix to use for the Authorization header
171        auth_header_name: The name of the Authorization header
172    """
173
174    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
175    _base_url: str = field(alias="base_url")
176    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
177    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
178    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
179    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
180    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
181    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
182    _client: httpx.Client | None = field(default=None, init=False)
183    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
184
185    token: str = field(repr=False)
186    prefix: str = "Bearer"
187    auth_header_name: str = "Authorization"
188
189    def with_headers(self, headers: dict[str, str]) -> "AuthenticatedClient":
190        """Get a new client matching this one with additional headers"""
191        if self._client is not None:
192            self._client.headers.update(headers)
193        if self._async_client is not None:
194            self._async_client.headers.update(headers)
195        return evolve(self, headers={**self._headers, **headers})
196
197    def with_cookies(self, cookies: dict[str, str]) -> "AuthenticatedClient":
198        """Get a new client matching this one with additional cookies"""
199        if self._client is not None:
200            self._client.cookies.update(cookies)
201        if self._async_client is not None:
202            self._async_client.cookies.update(cookies)
203        return evolve(self, cookies={**self._cookies, **cookies})
204
205    def with_timeout(self, timeout: httpx.Timeout) -> "AuthenticatedClient":
206        """Get a new client matching this one with a new timeout configuration"""
207        if self._client is not None:
208            self._client.timeout = timeout
209        if self._async_client is not None:
210            self._async_client.timeout = timeout
211        return evolve(self, timeout=timeout)
212
213    def set_httpx_client(self, client: httpx.Client) -> "AuthenticatedClient":
214        """Manually set the underlying httpx.Client
215
216        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
217        """
218        self._client = client
219        return self
220
221    def get_httpx_client(self) -> httpx.Client:
222        """Get the underlying httpx.Client, constructing a new one if not previously set"""
223        if self._client is None:
224            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
225            self._client = httpx.Client(
226                base_url=self._base_url,
227                cookies=self._cookies,
228                headers=self._headers,
229                timeout=self._timeout,
230                verify=self._verify_ssl,
231                follow_redirects=self._follow_redirects,
232                **self._httpx_args,
233            )
234        return self._client
235
236    def __enter__(self) -> "AuthenticatedClient":
237        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
238        self.get_httpx_client().__enter__()
239        return self
240
241    def __exit__(self, *args: Any, **kwargs: Any) -> None:
242        """Exit a context manager for internal httpx.Client (see httpx docs)"""
243        self.get_httpx_client().__exit__(*args, **kwargs)
244
245    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> "AuthenticatedClient":
246        """Manually set the underlying httpx.AsyncClient
247
248        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
249        """
250        self._async_client = async_client
251        return self
252
253    def get_async_httpx_client(self) -> httpx.AsyncClient:
254        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
255        if self._async_client is None:
256            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
257            self._async_client = httpx.AsyncClient(
258                base_url=self._base_url,
259                cookies=self._cookies,
260                headers=self._headers,
261                timeout=self._timeout,
262                verify=self._verify_ssl,
263                follow_redirects=self._follow_redirects,
264                **self._httpx_args,
265            )
266        return self._async_client
267
268    async def __aenter__(self) -> "AuthenticatedClient":
269        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
270        await self.get_async_httpx_client().__aenter__()
271        return self
272
273    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
274        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
275        await self.get_async_httpx_client().__aexit__(*args, **kwargs)

103class AuthenticationError(APIError):
104    """Raised on ``401 Unauthorized``.
105
106    Typically means the API key is missing, invalid, or revoked.
107    """

124class BadRequestError(APIError):
125    """Raised on ``400 Bad Request``.
126
127    The request body or query parameters failed server-side validation.
128    Inspect ``body`` for details.
129    """

 16@define
 17class Client:
 18    """A class for keeping track of data related to the API
 19
 20    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
 21
 22        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
 23
 24        ``cookies``: A dictionary of cookies to be sent with every request
 25
 26        ``headers``: A dictionary of headers to be sent with every request
 27
 28        ``timeout``: The maximum amount of a time a request can take. API functions will raise
 29        httpx.TimeoutException if this is exceeded.
 30
 31        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
 32        but can be set to False for testing purposes.
 33
 34        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
 35
 36        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
 37
 38
 39    Attributes:
 40        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatus if the API returns a
 41            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
 42            argument to the constructor.
 43    """
 44    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
 45    _base_url: str = field(alias="base_url")
 46    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
 47    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
 48    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
 49    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
 50    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
 51    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
 52    _client: httpx.Client | None = field(default=None, init=False)
 53    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
 54
 55    def with_headers(self, headers: dict[str, str]) -> "Client":
 56        """Get a new client matching this one with additional headers"""
 57        if self._client is not None:
 58            self._client.headers.update(headers)
 59        if self._async_client is not None:
 60            self._async_client.headers.update(headers)
 61        return evolve(self, headers={**self._headers, **headers})
 62
 63    def with_cookies(self, cookies: dict[str, str]) -> "Client":
 64        """Get a new client matching this one with additional cookies"""
 65        if self._client is not None:
 66            self._client.cookies.update(cookies)
 67        if self._async_client is not None:
 68            self._async_client.cookies.update(cookies)
 69        return evolve(self, cookies={**self._cookies, **cookies})
 70
 71    def with_timeout(self, timeout: httpx.Timeout) -> "Client":
 72        """Get a new client matching this one with a new timeout configuration"""
 73        if self._client is not None:
 74            self._client.timeout = timeout
 75        if self._async_client is not None:
 76            self._async_client.timeout = timeout
 77        return evolve(self, timeout=timeout)
 78
 79    def set_httpx_client(self, client: httpx.Client) -> "Client":
 80        """Manually set the underlying httpx.Client
 81
 82        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
 83        """
 84        self._client = client
 85        return self
 86
 87    def get_httpx_client(self) -> httpx.Client:
 88        """Get the underlying httpx.Client, constructing a new one if not previously set"""
 89        if self._client is None:
 90            self._client = httpx.Client(
 91                base_url=self._base_url,
 92                cookies=self._cookies,
 93                headers=self._headers,
 94                timeout=self._timeout,
 95                verify=self._verify_ssl,
 96                follow_redirects=self._follow_redirects,
 97                **self._httpx_args,
 98            )
 99        return self._client
100
101    def __enter__(self) -> "Client":
102        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
103        self.get_httpx_client().__enter__()
104        return self
105
106    def __exit__(self, *args: Any, **kwargs: Any) -> None:
107        """Exit a context manager for internal httpx.Client (see httpx docs)"""
108        self.get_httpx_client().__exit__(*args, **kwargs)
109
110    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> "Client":
111        """Manually set the underlying httpx.AsyncClient
112
113        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
114        """
115        self._async_client = async_client
116        return self
117
118    def get_async_httpx_client(self) -> httpx.AsyncClient:
119        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
120        if self._async_client is None:
121            self._async_client = httpx.AsyncClient(
122                base_url=self._base_url,
123                cookies=self._cookies,
124                headers=self._headers,
125                timeout=self._timeout,
126                verify=self._verify_ssl,
127                follow_redirects=self._follow_redirects,
128                **self._httpx_args,
129            )
130        return self._async_client
131
132    async def __aenter__(self) -> "Client":
133        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
134        await self.get_async_httpx_client().__aenter__()
135        return self
136
137    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
138        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
139        await self.get_async_httpx_client().__aexit__(*args, **kwargs)

102@attrs.frozen
103class ClientExtension:
104    """Declarative configuration bundle for downstream SDK integration.
105
106    All fields are optional. Pass an instance to `IonQClient` via the
107    ``extension`` parameter to customize client behavior.
108
109    Attributes:
110        user_agent_token: Extra token appended to the ``User-Agent`` header
111            (e.g. ``"my-sdk/1.0"``).
112        default_headers: Headers merged into every request.
113        event_hooks: Sync `EventHook` instances invoked on every request.
114        async_event_hooks: Async `AsyncEventHook` instances invoked on
115            every async request.
116        retryable_status_codes: HTTP status codes that should trigger a retry.
117            Overrides the default set (429, 500, 502, 503, 520-529).
118        max_retries: Maximum retry attempts. Overrides the default of 2.
119        timeout: Request timeout. Overrides the default of 60 seconds.
120        transport_wrapper: Callable that wraps the sync transport, useful for
121            adding middleware (e.g. caching, tracing).
122        async_transport_wrapper: Callable that wraps the async transport.
123        error_mapper: Callable that maps exceptions raised by the transport
124            to downstream-specific exception types. Return the original
125            exception to leave it unchanged.
126        debug_hooks: If ``True``, hook exceptions are re-raised instead of
127            being logged and suppressed. Useful during development.
128    """
129
130    user_agent_token: str | None = None
131    default_headers: dict[str, str] = attrs.Factory(dict)
132    event_hooks: tuple[EventHook, ...] = ()
133    async_event_hooks: tuple[AsyncEventHook, ...] = ()
134    retryable_status_codes: frozenset[int] | None = None
135    max_retries: int | None = None
136    timeout: httpx.Timeout | None = None
137    transport_wrapper: Callable[[httpx.BaseTransport], httpx.BaseTransport] | None = None
138    async_transport_wrapper: Callable[[httpx.AsyncBaseTransport], httpx.AsyncBaseTransport] | None = None
139    error_mapper: Callable[[Exception], Exception] | None = None
140    debug_hooks: bool = False

47@runtime_checkable
48class EventHook(Protocol):
49    """Protocol for observing HTTP requests and responses (sync).
50
51    Implement this protocol and pass instances via
52    `ClientExtension.event_hooks` to receive callbacks on every request.
53
54    Hook exceptions are logged and suppressed by default. Set
55    ``debug_hooks=True`` on `ClientExtension` to re-raise them instead.
56    """
57
58    def on_request(self, request: httpx.Request) -> None:
59        """Called after the request is built but before it is sent.
60
61        Args:
62            request: The outgoing HTTP request.
63        """
64        ...
65
66    def on_response(self, request: httpx.Request, response: httpx.Response) -> None:
67        """Called after a response is received.
68
69        Args:
70            request: The original HTTP request.
71            response: The HTTP response. The body has already been read.
72        """
73        ...

 40def IonQClient(
 41    *,
 42    api_key: str | None = None,
 43    base_url: str = DEFAULT_BASE_URL,
 44    max_retries: int | None = None,
 45    timeout: httpx.Timeout | None = None,
 46    additional_user_agent: str | None = None,
 47    extension: ClientExtension | None = None,
 48    **kwargs,
 49) -> AuthenticatedClient:
 50    """Create an authenticated IonQ API client.
 51
 52    This is the recommended entry point for using the library. It handles
 53    authentication, retry configuration, User-Agent construction, and transport
 54    setup for both sync and async usage.
 55
 56    Args:
 57        api_key: IonQ API key. If not provided, reads the ``IONQ_API_KEY``
 58            environment variable.
 59        base_url: API base URL. Defaults to the IonQ production API.
 60        max_retries: Maximum retry attempts for transient errors (429, 5xx).
 61            Defaults to 2. Set to 0 to disable retries.
 62        timeout: Request timeout as an ``httpx.Timeout`` instance. Defaults to
 63            60 seconds with a 10-second connect timeout.
 64        additional_user_agent: Extra token appended to the User-Agent header,
 65            useful for identifying calling applications.
 66        extension: A `ClientExtension` bundle provided by a downstream SDK.
 67            Allows injecting hooks, custom headers, transport wrappers, and
 68            error mappers.
 69        **kwargs: Passed through to `AuthenticatedClient`.
 70
 71    Returns:
 72        An `AuthenticatedClient` configured with retry transport and
 73        authentication headers, ready for both sync and async API calls.
 74
 75    Raises:
 76        ValueError: If no API key is provided and ``IONQ_API_KEY`` is not set.
 77
 78    Examples:
 79        Basic usage with environment variable:
 80
 81        ```python
 82        from ionq_core import IonQClient
 83        from ionq_core.api.backends import get_backends
 84
 85        client = IonQClient()
 86        backends = get_backends.sync(client=client)
 87        ```
 88
 89        Explicit configuration:
 90
 91        ```python
 92        import httpx
 93        from ionq_core import IonQClient
 94
 95        client = IonQClient(
 96            api_key="your-api-key",
 97            max_retries=5,
 98            timeout=httpx.Timeout(30.0, connect=10.0),
 99        )
100        ```
101
102        Async usage with context manager:
103
104        ```python
105        async with IonQClient() as client:
106            backends = await get_backends.asyncio(client=client)
107        ```
108    """
109    key = api_key or os.environ.get("IONQ_API_KEY")
110    if not key:
111        raise ValueError("api_key or IONQ_API_KEY environment variable required")
112
113    if not base_url.startswith("https://"):
114        warnings.warn(
115            f"base_url {base_url!r} does not use HTTPS. API keys will be sent in cleartext.",
116            UserWarning,
117            stacklevel=2,
118        )
119    if kwargs.get("verify_ssl") is False:
120        warnings.warn(
121            "verify_ssl=False disables TLS certificate verification. "
122            "Your API key may be intercepted by a network attacker.",
123            UserWarning,
124            stacklevel=2,
125        )
126
127    ext = extension or ClientExtension()
128    ua_parts = [
129        f"ionq-core/{__version__}",
130        f"python/{platform.python_version()}",
131        f"httpx/{httpx.__version__}",
132        f"os/{platform.system().lower()}",
133        *filter(None, (additional_user_agent, ext.user_agent_token)),
134    ]
135    user_agent = " ".join(ua_parts)
136    effective_timeout = timeout or ext.timeout or DEFAULT_TIMEOUT
137    effective_retries = next(v for v in (max_retries, ext.max_retries, DEFAULT_MAX_RETRIES) if v is not None)
138
139    headers = {**ext.default_headers, "User-Agent": user_agent}
140
141    sync_transport = async_transport = build_transport(
142        effective_retries,
143        ext.retryable_status_codes or RETRYABLE_STATUS_CODES,
144    )
145
146    if ext.event_hooks or ext.error_mapper:
147        sync_transport = HookTransport(
148            sync_transport,
149            ext.event_hooks,
150            debug=ext.debug_hooks,
151            error_mapper=ext.error_mapper,
152        )
153    if ext.async_event_hooks or ext.error_mapper:
154        async_transport = HookTransport(
155            async_transport,
156            ext.async_event_hooks,
157            debug=ext.debug_hooks,
158            error_mapper=ext.error_mapper,
159        )
160    if ext.transport_wrapper:
161        sync_transport = ext.transport_wrapper(sync_transport)
162    if ext.async_transport_wrapper:
163        async_transport = ext.async_transport_wrapper(async_transport)
164
165    client = AuthenticatedClient(
166        base_url=base_url,
167        token=key,
168        prefix=_AUTH_PREFIX,
169        auth_header_name=_AUTH_HEADER,
170        timeout=effective_timeout,
171        headers=headers,
172        httpx_args={"transport": sync_transport},
173        **kwargs,
174    )
175    # `set_async_httpx_client` bypasses `AuthenticatedClient`'s lazy auth-header
176    # injection (see generated `client.py::get_async_httpx_client`), so we merge
177    # `Authorization` in manually here. The `_verify_ssl` / `_follow_redirects`
178    # fields are private on the generated `AuthenticatedClient` but are the only
179    # way to mirror the caller's choices onto the async transport; do not add a
180    # public accessor in the hand-written layer — they belong to generated code.
181    client.set_async_httpx_client(
182        httpx.AsyncClient(
183            base_url=base_url,
184            headers={**headers, _AUTH_HEADER: f"{_AUTH_PREFIX} {key}"},
185            timeout=effective_timeout,
186            transport=async_transport,
187            verify=client._verify_ssl,
188            follow_redirects=client._follow_redirects,
189        )
190    )
191    return client