GeezerVison

Problem

A URL's own query string was silently dropped whenever params were sent:

The cause is upstream: httpx2.URL(url, params=...) replaces the query rather than merging, and httpx2.Client._merge_queryparams merges only client and request params. httpware passed params straight through.

Upstream status: pydantic/httpx2#905 is open, and fix PR pydantic/httpx2#966 has been open since 2026-05 without review. The original httpx maintainer treated the replace behaviour as intended (encode/httpx#3433). If #966 lands, this change still yields the same URL and the helper can be removed.

Fix

_merge_url_query folds the URL's query into params before handing off to httpx2. It is applied in build_request, the per-verb methods (_prepare_request) and stream, on both Client and AsyncClient.

• Precedence: client params < URL query < per-request params; the per-request value wins on the same key.
• Repeated URL keys (?a=1&a=2) are kept.
• When the URL has no query, or no params are sent at all (per-request or client-level), the URL passes through untouched, so pass-through links such as pagination next keep their original encoding.

Behaviour change

• Code relying on params replacing the URL's query now gets a merge.
• When a merge does happen, httpx2 re-encodes the URL's query (e.g. a raw + may become %20); semantically equivalent.
• Not addressed: a query inside base_url is still dropped by httpx2's _merge_url.

Tests

tests/test_url_query_merge.py: 44 cases across build_request, get and stream for both clients, written first (37 failed before the fix). Full suite, ruff, ty and eof-fixer pass locally.