Skip to content

feat: make type checkers reject unknown client options - #150

Merged
lesnik512 merged 1 commit into
mainfrom
feat/closed-client-options
Oct 1, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
feat/closed-client-options

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Problem

Since 0.18.0, AsyncClient/Client take their httpx2 options as **httpx2_options: Unpack[_AsyncClientOptions]. pyright and mypy reject an unknown key there, such as verfy= or the refused cert=, but ty does not. httpware, jwks-client and semvertag all type-check with ty, so in these repos those mistakes only surface at runtime, when the constructor's key check raises TypeError.

ty's behaviour is intentional. python/typing#2272 lets checkers read **kwargs: Unpack[TD] as also accepting extra keys, and a ty maintainer confirmed on astral-sh/ty#154 that it won't change. The suggested fix is a closed TypedDict (PEP 728). That's built into typing from Python 3.15 and available today through typing_extensions.

Change

  • _AsyncClientOptions and _ClientOptions are declared with closed=True. The shared _ClientOptionsBase stays open, because PEP 728 doesn't let a subclass of a closed TypedDict add keys. All three are now typing_extensions.TypedDict.
  • New runtime dependency: typing-extensions>=4.14.1. Before this, httpx2 was the only one, and httpx2 pulls in typing_extensions only below 3.13.
  • The runtime key check stays, for callers who don't run a type checker.

Why the floor is 4.14.1

  • On Python 3.14, typing_extensions 4.12.2 through 4.13.2 return an empty __optional_keys__ for a closed TypedDict. The constructor's key check reads that attribute, so it would reject every option, verify included. 4.14.0 is correct on 3.11, 3.12, 3.13, 3.14 and 3.14t.
  • 4.14.1 rather than 4.14.0, because the cp314 pydantic floor (2.12.0) requires typing-extensions>=4.14.1. With 4.14.0, the floors job on 3.14 can't resolve.

Tests

  • New tests test_type_checkers_reject_unsupported_{async,sync}_options make literal calls such as AsyncClient(verfy=True) and AsyncClient(cert=...), each with # ty: ignore[unknown-argument]. Before the change, ty reports four unused-ignore warnings and ty check exits 1. After it, the suppressions are used. At runtime, each call still has to raise TypeError.
  • The floor is guarded by the floors job. On 3.14, downgrading to typing-extensions==4.13.2 fails 78 of the option tests.
  • Checked locally: ruff, ty, 957 tests at 100% coverage. I also reproduced the floors job (uv pip compile --resolution lowest-direct) on 3.11, 3.12, 3.13, 3.14 and 3.14t, and all 957 tests pass on each.

The option TypedDicts behind **httpx2_options are now closed (PEP 728)
via typing_extensions, so ty reports a misspelled or refused option such
as verfy= or cert= at type-check time; pyright and mypy already did.
@lesnik512
lesnik512 merged commit 85e247f into main Oct 1, 2026
13 checks passed
@lesnik512
lesnik512 deleted the feat/closed-client-options branch October 1, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant