Changing the unexpected default behavior for URL + params

[jamesbraza]

With httpx==0.28.1's URL there is a footgun behavior where the params arg will clobber any params in the url string:

from httpx import URL

print(
    URL("https://httpbin.org/get?name=stub", params={"language": "python"})
)
# https://httpbin.org/get?language=python

This was also recently reported as a bug here: #3621

Why is silent clobbering the default behavior? Imo this behavior is both unexpected and hard to debug

[ketpatil77]

In 0.28.1, the constructor's params= replaces the URL's query. To request a merge explicitly, build the URL first and use its public copy_merge_params() method:

import httpx

url = httpx.URL("https://httpbin.org/get?name=stub")
url = url.copy_merge_params({"language": "python"})
assert str(url) == "https://httpbin.org/get?name=stub&language=python"

# Send that URL directly, without passing a second params= argument.
# response = httpx.get(url)

This also keeps the original URL immutable. If an incoming key already exists, the incoming value replaces that key's previous values; unrelated keys remain. For example, merging {"name": "replacement"} replaces name=stub.

That gives you the intended behavior without an additional query-string library. It is a workaround using the existing API, not a claim that the default behavior or the linked issue has changed.

HTTPX 0.28.1 URL implementation defines copy_merge_params() separately from query replacement. AI-assisted; checked preserved keys, replacement of an overlapping key and repeated values locally on HTTPX 0.28.1.