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

httpx/_urls.py

@@ -110,8 +110,40 @@ 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
@@ -467,6 +467,21 @@ class ExternalURLClass:  # representing external URL class
         httpx.URL(ExternalURLClass())  # type: ignore
 
 
+def test_url_invalid_type_with_params():
+    with pytest.raises(TypeError):
+        httpx.URL(123, params={"a": "b"})  # type: ignore
+
+
+def test_url_with_params_none():
+    # Test with existing query parameters
+    url = httpx.URL("https://example.com?existing=param", params=None)
+    assert "existing=param" in str(url)
+
+    # Test without existing query parameters
+    url = httpx.URL("https://example.com", params=None)
+    assert str(url) == "https://example.com"
+
+
 def test_url_with_invalid_component():
     with pytest.raises(TypeError) as exc:
         httpx.URL(scheme="https", host="www.example.com", incorrect="/")