Fix URL params to merge with existing query parameters instead of replacing them

When creating a URL with `URL(url, params=params)` or `Request(method, url, params=params)`,
the params now merge with existing query parameters in the URL instead of completely
replacing them. This makes the behavior consistent with the Python requests library.

Before:
  URL("https://example.com?a=1", params={"b": "2"})
  Result: "https://example.com?b=2"  # 'a=1' was lost

After:
  URL("https://example.com?a=1", params={"b": "2"})
  Result: "https://example.com?a=1&b=2"  # parameters merged

Special cases handled:
- Empty dict params={} preserves existing query parameters
- None params preserves existing query parameters
- QueryParams objects are used directly (for copy_* methods)
- Overlapping parameter names are overridden by new values

Fixes #652

Author: ferstar

httpx/_urls.py

@@ -110,8 +110,34 @@ def __init__(self, url: URL | str = "", **kwargs: typing.Any) -> None:
                 # Ensure that empty params use `kwargs["query"] = None` rather
                 # than `kwargs["query"] = ""`, so that generated URLs do not
                 # include an empty trailing "?".
+                #
+                # Merge new params with existing query parameters instead of replacing them.
                 params = kwargs.pop("params")
-                kwargs["query"] = None if not params else str(QueryParams(params))
+                # Get existing query parameters from the URL
+                if isinstance(url, str):
+                    parsed_url = urlparse(url)
+                    existing_params = QueryParams(parsed_url.query)
+                elif isinstance(url, URL):
+                    existing_params = url.params
+                else:
+                    existing_params = QueryParams()
+
+                if isinstance(params, QueryParams):
+                    # If params is a QueryParams object, use it directly (for copy_* methods)
+                    kwargs["query"] = None if not params else str(params)
+                elif params:
+                    # Merge existing parameters with new params (dict, list, etc.)
+                    merged_params = existing_params.merge(params)
+                    kwargs["query"] = None if not merged_params else str(merged_params)
+                elif isinstance(params, dict) and not params:
+                    # If params is an empty dict, keep existing query parameters
+                    kwargs["query"] = None if not existing_params else str(existing_params)
+                elif params is None:
+                    # If params is None, keep existing query parameters
+                    kwargs["query"] = None if not existing_params else str(existing_params)
+                else:
+                    # Fallback case
+                    kwargs["query"] = None if not params else str(params)
 
         if isinstance(url, str):
             self._uri_reference = urlparse(url, **kwargs)

tests/models/test_requests.py

@@ -235,7 +235,7 @@ def test_request_params():
     request = httpx.Request(
         "GET", "http://example.com?c=3", params={"a": "1", "b": "2"}
     )
-    assert str(request.url) == "http://example.com?a=1&b=2"
+    assert str(request.url) == "http://example.com?c=3&a=1&b=2"
 
     request = httpx.Request("GET", "http://example.com?a=1", params={})
-    assert str(request.url) == "http://example.com"
+    assert str(request.url) == "http://example.com?a=1"

tests/models/test_url.py

@@ -159,8 +159,8 @@ def test_url_params():
     url = httpx.URL(
         "https://example.org:123/path/to/somewhere?b=456", params={"a": "123"}
     )
-    assert str(url) == "https://example.org:123/path/to/somewhere?a=123"
-    assert url.params == httpx.QueryParams({"a": "123"})
+    assert str(url) == "https://example.org:123/path/to/somewhere?b=456&a=123"
+    assert url.params == httpx.QueryParams({"b": "456", "a": "123"})
 
 
 # Tests for username and password