The case for immutable QueryParams

[tomchristie]

I'd like to propose a change to our QueryParams interface, starting with 0.18.

Our URL model is immutable, which is a very nice sensible property for it to have. Similarly, the hyperlink package has the same design constraint there.

Changing a URL always creates a new instance, eg. url = url.copy_with(scheme="https")

However, our QueryParams model is currently mutable. So eg. q["a"] = "123" or q.update({"a": "123"}) both change the existing instance, rather than returning a new one. That's actually a bit of a grungy design difference vs. our URL model.

It also has an awkward impact. I'd like us to be able to add a url.params property, since it makes sense in terms of consistency of our API. But it wouldn't currently work in a neat way, because eg... it'd allow for weird usages like url.params["a"] = "123" which looks like it'd mutate the URL, but actually wouldn't have any effect. It would mutate a QueryParams instance that's returned by the url.params property, and then discard it.

An immutable QueyParams model would just be plain nicer all round.

I'd suggest we drop __setitem__ and update() and instead have an API of methods that each return new instances.

Following hyperlink, we'd likely want set(), add(), and remove():

q = httpx.QueryParams()

q = q.set("a", "123")
assert q == httpx.QueryParams("a=123")

q = q.add("a", "456")
assert q == httpx.QueryParams("a=123&a=456")

q = q.remove("a")
assert q == httpx.QueryParams("")

Really we also want an equivalent of .update(other), although I think it's better not to name it update since that more easily lead to unexpected coding errors, given expectations that dict.update is a mutating method, so I'd suggest .merge(other):

q = httpx.QueryParams({"a": "123")
assert q == httpx.QueryParams("a=123")

q = q.merge({"b": "456", "c": "789"})
assert q == httpx.QueryParams("a=123&b=456&c=789")

We could either do this with a deprecation period for __setitem__ and update, or else issue it as an outright change.

Our exposure here is pretty low - we don't actually document any of the QueryParam mutating methods anywhere in the docs, and are only exposing them for nice API consistency. The only place we use them internally is a single case in the client where we merge the client params with any per-request params.

It'll also let us extend out the URL model in a neat way, so that...

u = httpx.URL("https://www.example.com/?search=testing")  # URL is immutable.
assert u.params == httpx.QueryParams("search=testing")    # URL parameters are also immutable.

A further neat extension to really round out our URL manipulation would then be to add the following...

class URL:
    ...

    def copy_set_param(self, key, value):
        return self.copy_with(params=self.params.add(key, value))

    def copy_add_param(self, key, value):
         return self.copy_with(params=self.params.set(key, value))

    def copy_remove_param(self, key):
        return self.copy_with(params=self.params.remove(key))

    def copy_merge_params(self, params):
        return self.copy_with(params=self.params.merge(params))

To support usages such as...

u = httpx.URL("https://www.example.com/")
u = u.copy_set_param("search", "testing")
assert u == httpx.URL("https://www.example.com/?search=testing")