Simplify the hand-written layer and fix client contract bugs #97
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -19,6 +19,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | |
|
|
||
| ### Added | ||
|
|
||
| - `Matrix2x2` and `Matrix4x4` are now exported from `ionq_core.gates`; they were already documented as the return types of the gate unitaries. | ||
| - `QctrlQaoaJobCreationPayload` and `QctrlQaoaJobInput` for submitting Q-CTRL QAOA maxcut combinatorial-optimization jobs via `create_job`. The `create_job` body union now also accepts `QctrlQaoaJobCreationPayload`. | ||
| - `cost_model` optional field on `BaseJob`, `GetCircuitJobResponse`, and `GetJobResponse`, typed as `ApiCostModel` (`"QCT"` or `"2QGE_operations"`). | ||
| - `clone_job` endpoint (`POST /jobs/{UUID}/clone`) and its `CloneJobPayload` model for resubmitting an existing job with optional overrides. | ||
|
|
@@ -28,10 +29,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | |
|
|
||
| ### Changed | ||
|
|
||
| - Every `APIError` now carries `retry_after` (parsed and clamped from the `Retry-After` header). Previously only `RateLimitError` exposed it and the value was discarded for other statuses such as 503, where RFC 9110 also allows the header. | ||
| - POST requests are no longer retried automatically by the default transport. The API has no idempotency-key mechanism, so replaying `create_job` / `create_session` / `end_session` after an ambiguous gateway 5xx could duplicate billable work; idempotent methods retry as before. Callers that want POST retries must supply their own transport and handle deduplication. | ||
| - `NativeCircuitInput.qubits` and `JsonMultiCircuitInput.qubits` are now `int | Unset` (previously `float | Unset`), matching upstream's tightening to `format: int32, minimum: 1`. `QisCircuitInput.qubits` already had this type locally via the OpenAPI overlay; that overlay action has been removed now that upstream is correct natively. | ||
| - Regenerated with `openapi-python-client` 0.29.0. Generated models now parse timestamps with the standard library (`datetime.fromisoformat`) instead of `dateutil.parser.isoparse`. | ||
|
|
||
| ### Fixed | ||
|
|
||
| - `IonQClient(headers=...)` no longer raises `TypeError`; caller headers are merged beneath the extension defaults and the generated `User-Agent`. | ||
| - `cookies` passed to `IonQClient` now reach the async client as well (previously the sync client only). | ||
| - `IonQClient()` no longer builds the TLS trust store twice; the SSL context is created once and shared by the sync and async transports. | ||
|
|
||
| ### Removed | ||
|
|
||
| - `get_compiled_file` endpoint (`GET /jobs/{UUID}/circuits/{lang}`) and its `GetCompiledFileLang` enum, removed upstream in favor of `get_job_artifact`. Compiled circuits are now fetched as artifacts by id rather than by `lang` (`"native"` / `"qasm3"`). | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,15 +30,15 @@ This project uses [`uv`](https://docs.astral.sh/uv/) for Python and dependency m | |
| git clone https://github.com/ionq/ionq-core-python | ||
| cd ionq-core-python | ||
| uv sync | ||
| uvx pre-commit install | ||
| ``` | ||
|
|
||
| The supported Python floor is set by `requires-python` in `pyproject.toml`; the CI matrix in [`ci.yml`](.github/workflows/ci.yml) is the source of truth for tested interpreters. | ||
|
|
||
| ## Running checks locally | ||
|
|
||
| ```sh | ||
| uv run pytest # unit tests | ||
| uv run ruff check # lint | ||
| uv run ruff format --check # format check (drop --check to apply) | ||
| uv run ty check ionq_core/ # type check | ||
|
|
@@ -64,13 +64,7 @@ To regenerate `ionq_core/api/`, `ionq_core/models/`, and the root-level generate | |
| ```sh | ||
| uv sync --group regen | ||
| curl -sf https://api.ionq.co/v0.4/api-docs -o openapi.json | ||
| uv run oas-patch overlay openapi.json openapi-overlay.yaml -o /tmp/patched-spec.json | ||
| uv run openapi-python-client generate \ | ||
| --path /tmp/patched-spec.json \ | ||
| --meta none \ | ||
|
|
@@ -88,7 +82,7 @@ Commit the regenerated files alongside the spec or template change that caused t | |
|
|
||
| 1. Fork the repository and create a topic branch off `main`. | ||
| 2. Make your changes; add or update tests for any hand-written code you touch. | ||
| 3. Run the local checks above and `uvx pre-commit run --all-files`. | ||
| 4. Push and open a PR against `main`. Fill in the **Summary** and **Test plan** sections of the template. | ||
| 5. CI must pass: lint, tests across the supported-Python matrix, the generated-code staleness check, `pip-audit`, and `zizmor` when workflow files change. A reviewer from `@ionq/developer-tools` will review. | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -63,16 +63,11 @@ print(probs.additional_properties) | |
|
|
||
| Each generated endpoint module exposes four callables: `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`. The `sync` and `asyncio` variants return the parsed body; the `_detailed` variants return a `Response[T]` with the status code, headers, and parsed body. | ||
|
|
||
| For client options, error classes, retry behavior, pagination, polling, sessions, and downstream-SDK extension hooks, see the [API reference](https://ionq.github.io/ionq-core-python/). | ||
|
|
||
| ## Versioning | ||
|
|
||
| This package follows [SemVer 2.0](https://semver.org/spec/v2.0.0.html), independent of the upstream REST API version - pass an explicit `base_url` to `IonQClient` to pin against a different API. Print the installed version with `ionq_core.__version__`. | ||
|
|
||
| The full release history is in [CHANGELOG.md](https://github.com/ionq/ionq-core-python/blob/main/CHANGELOG.md). | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,11 +9,6 @@ | |
| 500, 502, 503, and 520-529 with exponential backoff (factor 0.5, jitter 0.5, | ||
| max 60s); POST is never retried because the API has no idempotency keys, so a | ||
| replay after an ambiguous 5xx could duplicate billable work. | ||
| """ | ||
|
|
||
| import json | ||
|
|
@@ -174,7 +169,11 @@ def build_transport( | |
| # POST is deliberately not retryable: without idempotency keys, a replay | ||
| # after an ambiguous 5xx could duplicate billable jobs. | ||
| ) | ||
| # Build the SSL context once: handing `verify` to each transport would load | ||
| # the CA bundle from disk twice per client (create_ssl_context passes an | ||
| # ssl.SSLContext through unchanged, so pinned contexts keep their identity). | ||
| ctx = httpx.create_ssl_context(verify=verify) | ||
| return ErrorRaisingTransport( | ||
| RetryTransport(transport=httpx.HTTPTransport(verify=ctx), retry=retry), | ||
| RetryTransport(transport=httpx.AsyncHTTPTransport(verify=ctx), retry=retry), | ||
| ) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,13 +9,15 @@ | |
| IonQError | ||
| +-- APIConnectionError # network / DNS failures | ||
| | +-- APITimeoutError # request timed out | ||
| +-- APIError # HTTP 4xx / 5xx responses (carries retry_after) | ||
| | +-- BadRequestError # 400 | ||
| | +-- AuthenticationError # 401 | ||
| | +-- PermissionDeniedError # 403 | ||
| | +-- NotFoundError # 404 | ||
| | +-- RateLimitError # 429 | ||
| | +-- ServerError # 5xx | ||
| +-- JobTimeoutError # polling deadline exceeded (ionq_core.polling) | ||
| +-- JobFailedError # polled job ended in failure (ionq_core.polling) | ||
| ``` | ||
|
|
||
| Example: | ||
|
|
@@ -50,7 +52,9 @@ class IonQError(Exception): | |
| """Base exception for all IonQ errors. | ||
|
|
||
| Catch this to handle any error raised by the library, including connection | ||
| failures, API errors, polling timeouts, and job failures. The one | ||
| exception outside this tree is ``errors.UnexpectedStatus``, raised only | ||
| for undocumented status codes when ``raise_on_unexpected_status`` is set. | ||
| """ | ||
|
|
||
|
|
||
|
|
@@ -80,6 +84,8 @@ class APIError(IonQError): | |
| or ``None`` if the body could not be read). | ||
| message: A human-readable error message extracted from the response, | ||
| or a default ``"HTTP <status>"`` string. | ||
| retry_after: Seconds to wait before retrying, from the ``Retry-After`` | ||
| header, or ``None`` if the server did not send a usable one. | ||
| request_id: The ``x-request-id`` header from the response, useful for | ||
| contacting IonQ support about a specific request. | ||
| """ | ||
|
|
@@ -89,11 +95,13 @@ def __init__( | |
| status_code: int, | ||
| body: dict | str | None = None, | ||
| message: str | None = None, | ||
| retry_after: float | None = None, | ||
| *, | ||
| request_id: str | None = None, | ||
| ) -> None: | ||
| self.status_code = status_code | ||
| self.body = body | ||
| self.retry_after = retry_after | ||
| self.request_id = request_id | ||
| self.message = message or f"HTTP {status_code}" | ||
| super().__init__(self.message) | ||
|
|
@@ -144,18 +152,6 @@ class RateLimitError(APIError): | |
| attribute into an unbounded wait. | ||
| """ | ||
|
|
||
|
|
||
| class ServerError(APIError): | ||
| """Raised on ``5xx`` server errors. | ||
|
|
@@ -184,9 +180,7 @@ def raise_for_status( | |
| ) -> None: | ||
| """Raise an appropriate `APIError` subclass for an HTTP error status. | ||
|
|
||
| Does nothing for status codes below 400. | ||
|
|
||
| Args: | ||
| status_code: The HTTP status code. | ||
|
|
@@ -207,6 +201,4 @@ def raise_for_status( | |
| if status_code < 400: | ||
| return | ||
| exc_cls = _STATUS_TO_EXCEPTION.get(status_code, ServerError if status_code >= 500 else APIError) | ||
| raise exc_cls(status_code, body, message, retry_after, request_id=request_id) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why is
tests/test_docs_consistency.pybeing mentioned here? it feels like running tests intestsis separate from the spec drift checking CI action here.