fix: reject unknown client and request options

Cargo.toml

@@ -28,6 +28,7 @@ abi3-py313 = ["pyo3/abi3-py313"]
 abi3-py314 = ["pyo3/abi3-py314"]
 
 [dependencies]
+derive-deftly = { version = "1.14.0", default-features = false, features = ["minimal-1"] }
 pingora-runtime = "0.9.0"
 tokio = { version = "1.53.2", features = ["rt-multi-thread", "sync", "time", "net", "macros"] }
 tokio-util = { version = "0.7.18", features = ["rt"] }

RELEASE.md

@@ -1,3 +1,11 @@
+## [unreleased]
+
+### Compatibility Notes
+
+- Unknown keyword arguments now raise `TypeError` when calling async or blocking client constructors, HTTP or WebSocket request methods and functions, `Http1Options`, `Http2Options`, `TlsOptions`, or `Proxy` factories. These arguments were previously ignored.
+- Set client-only options such as `connect_timeout` and `proxies` on `Client`; passing them to a request now raises `TypeError`. Use `proxy` to select a proxy for one request.
+- Async request calls check keyword names before returning a coroutine. Values for supported request keywords are still converted on first `await` or entry with `async with`.
+
 ## [0.11.0](https://github.com/0x676e67/wreq-python/compare/v0.10.2..v0.11.0) - 2026-04-13
 
 ### Features

docs/source/guide/basic.md

@@ -67,6 +67,18 @@ async with client.request(
 `query` and `form` accept dictionaries or lists of pairs. Pairs preserve
 repeated keys. Values can be strings, integers, floats or booleans.
 
+Client constructors and HTTP or WebSocket request methods reject unknown
+keyword arguments with `TypeError` when called, in both the async and blocking
+APIs. The same rule applies to module-level request functions, `Http1Options`,
+`Http2Options`, `TlsOptions`, and the
+`Proxy.http()`, `Proxy.https()`, `Proxy.all()` and `Proxy.unix()` factories.
+Set client-only options, such as `connect_timeout`, on `Client`.
+
+Client and protocol option values are converted at construction, and proxy
+option values during the factory call. Values for supported async request
+keywords are converted when the coroutine is first awaited or entered with
+`async with`; blocking requests convert them during the method or function call.
+
 ## Request bodies
 
 Use `json` for JSON, `form` for URL-encoded fields, and `body` for raw text or

python/wreq/blocking.py

@@ -216,6 +216,9 @@ def __str__(self) -> str: ...
 class Client:
     r"""
     A blocking client for making HTTP requests.
+
+    Unknown configuration or request keyword arguments raise `TypeError`
+    during the call.
     """
 
     runtime: Runtime

python/wreq/http1.py

@@ -10,6 +10,8 @@
 class Params(TypedDict):
     """
     All parameters for HTTP/1 connections.
+
+    Unknown keyword arguments raise `TypeError` when constructing `Http1Options`.
     """
 
     http09_responses: NotRequired[bool]

python/wreq/http2.py

@@ -268,6 +268,8 @@ def __str__(self) -> str:
 class Params(TypedDict):
     """
     All parameters for HTTP/2 connections.
+
+    Unknown keyword arguments raise `TypeError` when constructing `Http2Options`.
     """
 
     initial_window_size: NotRequired[int]

python/wreq/proxy.py

@@ -27,6 +27,8 @@ class Proxy:
     r"""
     A proxy server for a request.
     Supports HTTP, HTTPS, SOCKS4, SOCKS4a, SOCKS5, and SOCKS5h protocols.
+
+    Unknown keyword arguments passed to its factory methods raise `TypeError`.
     """
 
     @staticmethod

python/wreq/tls.py

@@ -254,6 +254,8 @@ def file(path: Path | str) -> "KeyLog":
 class Params(TypedDict):
     """
     All parameters for TLS connections.
+
+    Unknown keyword arguments raise `TypeError` when constructing `TlsOptions`.
     """
 
     alpn_protocols: NotRequired[Sequence[AlpnProtocol]]

python/wreq/wreq.py

@@ -539,6 +539,11 @@ def __str__(self) -> str: ...
 
 
 class ClientConfig(TypedDict):
+    """Keyword options for constructing async and blocking clients.
+
+    Unknown keys raise `TypeError` when passed to a `Client` constructor.
+    """
+
     runtime: NotRequired[Runtime | None]
     """Runtime for this client and its responses; None uses the shared default.
     Async clients reject a `CURRENT_THREAD` runtime with `ValueError`."""
@@ -819,6 +824,12 @@ class ClientConfig(TypedDict):
 
 
 class Request(TypedDict):
+    """Keyword options for HTTP request methods and module-level functions.
+
+    Unknown keys raise `TypeError` when the method or function is called. Set
+    client-only options, such as `connect_timeout`, on `Client`.
+    """
+
     emulation: NotRequired[emulation.Emulation | emulation.Profile]
     """
     The Emulation settings for the request.
@@ -987,6 +998,11 @@ class Request(TypedDict):
 
 
 class WebSocketRequest(TypedDict):
+    """Keyword options for WebSocket request methods and module-level functions.
+
+    Unknown keys raise `TypeError` when the method or function is called.
+    """
+
     emulation: NotRequired[emulation.Emulation | emulation.Profile]
     """
     The Emulation settings for the request.
@@ -1143,6 +1159,10 @@ async def __aexit__(self, _exc_type: Any, _exc_value: Any, _traceback: Any) -> N
 class Client:
     r"""
     A client for making HTTP requests.
+
+    Unknown client or request keyword arguments raise `TypeError` during the
+    call. Values for supported request keywords are converted when the coroutine
+    is first awaited or entered with `async with`.
     """
 
     runtime: Runtime