Fix URL parameter merging when both URL and params are provided

When a URL contains query parameters and additional params are passed via
the params argument, the original URL parameters were being dropped instead
of being merged together. This was inconsistent with requests library behavior.

This fix modifies the URL.__init__() to merge existing query parameters from
the URL with new parameters from the params argument, rather than replacing
them. When the same key exists in both, the new params take precedence.

Examples:
- URL("https://api.com/get?page=1", params={"size": 10})
  Before: https://api.com/get?size=10  (page lost)
  After: https://api.com/get?page=1&size=10  (merged)

- URL("https://api.com/get?a=old", params={"a": "new"})
  After: https://api.com/get?a=new  (overridden)

Fixes #3621

Author: veeceey

httpx/_urls.py

@@ -105,13 +105,36 @@ def __init__(self, url: URL | str = "", **kwargs: typing.Any) -> None:
                     kwargs[key] = value.decode("ascii")
 
             if "params" in kwargs:
-                # Replace any "params" keyword with the raw "query" instead.
+                # Merge any "params" keyword with existing query params.
+                #
+                # When a URL already has query parameters and additional params
+                # are provided, we merge them together rather than replacing.
+                # This matches the behavior of the requests library.
                 #
                 # Ensure that empty params use `kwargs["query"] = None` rather
                 # than `kwargs["query"] = ""`, so that generated URLs do not
                 # include an empty trailing "?".
                 params = kwargs.pop("params")
-                kwargs["query"] = None if not params else str(QueryParams(params))
+
+                # Get existing query params from the URL
+                if isinstance(url, str):
+                    parsed_url = urlparse(url)
+                    existing_params = QueryParams(parsed_url.query) if parsed_url.query else QueryParams()
+                elif isinstance(url, URL):
+                    existing_params = url.params
+                else:
+                    existing_params = QueryParams()
+
+                # Merge existing and new params
+                if params:
+                    merged_params = existing_params.merge(params)
+                    kwargs["query"] = str(merged_params) if merged_params else None
+                elif existing_params:
+                    # params is empty but URL has existing params - keep them
+                    kwargs["query"] = str(existing_params)
+                else:
+                    # Both empty - no query string
+                    kwargs["query"] = None
 
         if isinstance(url, str):
             self._uri_reference = urlparse(url, **kwargs)

tests/models/test_url.py

@@ -861,3 +861,61 @@ def test_ipv6_url_copy_with_host(url_str, new_host):
     assert url.host == "::ffff:192.168.0.1"
     assert url.netloc == b"[::ffff:192.168.0.1]:1234"
     assert str(url) == "http://[::ffff:192.168.0.1]:1234"
+
+
+def test_url_params_merge_with_existing_query():
+    """
+    Test that when constructing a URL with both existing query params
+    and a params argument, they are merged together.
+
+    Regression test for issue #3621.
+    """
+    # URL with existing query params + additional params argument
+    url = httpx.URL("https://example.com/get?page=post&s=list", params={"pid": 0, "tags": "test"})
+
+    assert url.path == "/get"
+    assert "page=post" in str(url)
+    assert "s=list" in str(url)
+    assert "pid=0" in str(url)
+    assert "tags=test" in str(url)
+
+    # Verify all params are present
+    params = dict(url.params)
+    assert params == {"page": "post", "s": "list", "pid": "0", "tags": "test"}
+
+
+def test_url_params_override_with_same_key():
+    """
+    Test that when a URL has existing query params and new params with
+    the same key are provided, the new params override the old ones.
+    """
+    url = httpx.URL("https://example.com/get?a=old&b=keep", params={"a": "new", "c": "add"})
+
+    params = dict(url.params)
+    assert params["a"] == "new"  # Overridden
+    assert params["b"] == "keep"  # Preserved
+    assert params["c"] == "add"  # Added
+
+
+def test_url_params_empty_dict_preserves_existing():
+    """
+    Test that passing an empty params dict doesn't remove existing URL params.
+    """
+    url = httpx.URL("https://example.com/get?x=5&y=6", params={})
+
+    assert "x=5" in str(url)
+    assert "y=6" in str(url)
+    params = dict(url.params)
+    assert params == {"x": "5", "y": "6"}
+
+
+def test_url_no_existing_params_with_params_arg():
+    """
+    Test that a URL without existing query params works normally with params argument.
+    """
+    url = httpx.URL("https://example.com/get", params={"a": "1", "b": "2"})
+
+    assert "a=1" in str(url)
+    assert "b=2" in str(url)
+    params = dict(url.params)
+    assert params == {"a": "1", "b": "2"}