Simplify the hand-written layer and fix client contract bugs - #97
Open
splch wants to merge 3 commits into
Open
Conversation
Result of a per-module simplification review (one reviewer per module/test pair, full gates enforced throughout): net -220 lines, behavior unchanged. - polling: fold _check_terminal's redundant terminal-status guard into its return (equivalent because "failed" is itself in _TERMINAL) - session: build the session settings once in __init__ instead of caching three single-use attributes for a lazy _build_settings call - extensions: async protocol docstrings now cross-reference their sync twins; drop the incorrect claim that on_response bodies are pre-read (the transport only reads bodies for >=400 responses, which raise) - transport/exceptions/gates/ionq_client: trim docstring text that was duplicated verbatim elsewhere on the same rendered pdoc page - tests: delete tests whose setup and assertions are strict subsets of other tests, merge the async counting stream into the sync one via dual inheritance, replace test_api's 28-line inline job payload with conftest's make_job_json, fold five AGENTS.md docs pins into one parametrized test - _url, pagination, conftest, and all integration tests: reviewed, already minimal All security behavior and its tests are unchanged: path-parameter rejection, Retry-After clamp, error-body read cap, verify_ssl plumbing, pagination cursor guard, credential repr hygiene, no POST retries. 273 tests pass with 100% branch coverage; ruff, ruff format, and ty are clean; regenerating the client produces no diff.
From a five-auditor holistic review of the repository:
- Every APIError now carries retry_after; RateLimitError's bespoke __init__
and the dispatcher's special case are gone. The transport already parsed
and clamped Retry-After for every status, so the value is no longer
discarded for non-429 responses (RFC 9110 allows the header on e.g. 503).
- IonQClient(headers=...) merges instead of raising TypeError, cookies now
reach the async client too, and the kwargs docstring states exactly which
keys do what (httpx_args is reserved).
- build_transport creates the TLS context once and shares it across the
sync and async transports instead of loading the CA bundle twice per
client (~6 ms and one redundant trust store per IonQClient()).
- EventHook docs now state that on_response fires only for successes and
that the optional on_error hook exists; it was fired by HookTransport but
documented nowhere the published docs render.
- gates exports Matrix2x2/Matrix4x4, which six docstrings already reference
as return types (they were dead links on the docs site).
- exceptions.py's hierarchy diagram includes the polling exceptions and
names errors.UnexpectedStatus as the one type outside the IonQError tree.
Tests: the three fake-transport doubles collapse into one conftest helper;
duplicates with named survivors are removed (get_jobs smoke vs pagination,
session none-response twins, 401 transport mapping, redundant isinstance
checks, an integration list check implied by its neighbor); new tests cover
the header merge, async cookies, shared SSL context, retry_after on 503,
and the previously untested {"error": ...} message key. The two CONTRIBUTING
spec-path pins merge into one strictly stronger test that also pins
spec-drift.yml's SPEC_URL to DEFAULT_BASE_URL.
- The SPDX post-hook also squeezes trailing newlines, so generated output satisfies pre-commit's end-of-file-fixer without fighting the staleness gate (39 files lose their blank final line). The no-op ruff check --fix-only hook is dropped; ruff format stays, it is load-bearing for the rendered __init__.py. - generated.yml: the dead overlay-missing fallback is removed (the overlay is tracked and required) and UV_FROZEN is set so the regen toolchain always matches uv.lock. - CONTRIBUTING mirrors the fallback removal; AGENTS.md's drifted third copy of the regen command becomes a pointer to CONTRIBUTING; both files use uvx pre-commit (plain pre-commit is not installed by uv sync); two self-duplicated sentences and a drift-sentinel claim no test enforces are removed. - README drops a stale parameter enumeration and a version-print fence. - dependabot drops the default day: monday; zizmor.yml drops the default token; pyproject drops two exclude_also patterns with zero occurrences and the unused RUF012 per-file-ignore; .gitattributes drops linguist-vendored on openapi.json (subsumed by linguist-generated).
This was referenced Aug 25, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
Part 2 of the stack #96 -> #97 -> #98 -> #95; merge bottom-up (each PR targets the previous one's branch). Simplifies the hand-written layer and fixes the contract bugs found while auditing it.
Contract fixes (behavior changes, itemized in the CHANGELOG)
APIErrornow carriesretry_after; previously the transport parsed the header for all statuses but discarded it except on 429 (RFC 9110 also allows it on e.g. 503).RateLimitError's bespoke__init__and the dispatcher special case are gone.IonQClient(headers=...)merges instead of raisingTypeError;cookiesnow reach the async client; the TLS context is built once and shared instead of loading the CA bundle twice per client.EventHookdocs now state thaton_responsefires only for successes and document the optionalon_errorhook;gatesexportsMatrix2x2/Matrix4x4, which its docstrings already referenced.Simplification (behavior unchanged)
test_api's inline payload replaced with the conftest factory.end-of-file-fixervs staleness-gate conflict is resolved by normalizing trailing newlines in the generation post-hook (39 generated files lose their blank final line).generated.ymldrops its dead overlay fallback and gainsUV_FROZEN; dead config removed (dependabot default day, zizmor default token, unused ruff/coverage entries, redundant gitattribute).Test plan
uv run pytestat this head: 271 passed (duplicates removed), 100% branch coverage held, warnings-as-errors.uv run ruff check,uv run ruff format --check,uv run ty check ionq_core/: clean.zizmorclean on changed workflows;pdocbuilds.Important
Most code in
ionq_core/is auto-generated and overwritten on regeneration.See CONTRIBUTING.md for which files are safe to edit.