Support cookies with value None

[tducret]

Summary

There are 3 kinds of request cookie headers.

request = httpx.Request("GET", "https://www.example.org", cookies=cookies)
request.headers["cookie"]  # <== This is the request cookie header we are talking about here

"name=value"

This is the classic case, already supported through :

cookies.set(name="name", value="value", domain="example.org")

"name="

Please note the trailing = sign here.
This is also supported, by passing an empty string as the cookie value :

cookies.set(name="name", value="", domain="example.org")

"name"

Please note there is no trailing = sign here.
This is not officially supported (yet), but can be achieved with :

cookies.set(name="name", value=None, domain="example.org")

It works because the cookie jar implementation in the standard library already deals with it.
Contrary to the httpx.Cookies.set method, the standard Cookie doesn't define strict typing for the value.

So this PR changes the httpx._models in order to support a cookie value which is None.
Otherwise the typing is incorrect, forcing the httpx to add a # type: ignore instruction.

The getter functions had to be updated as well, as the None was considered as a not found value.

2 new test cases are added in this PR to ensure the proper behavior.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

[T-256]

Suggested change

	class Cookies(typing.MutableMapping[str, typing.Optional[str]]):
	class Cookies(typing.MutableMapping[str, str | None]):

[tducret]

Hi @T-256 ! Actually, That was my initial attempt, but the test workflow failed with this notation.

[T-256]

Interesting, no problem then...

[tducret]

Is there anything else I can do before we merge it to the main branch?

[tomchristie]

Do name= and name have the same behavior?...

[tducret]

Do name= and name have the same behavior?...

According to the RFC for HTTP protocol :

If the name-value-pair string lacks a %x3D ("=") character, then the name string is empty, and the value string is the value of name-value-pair.

So it may depend on the server implementation, but I can confirm a case where the server considered name= and name as different.
Although this was already possible to create both kinds of cookies, this PR confirms this usage by changing the type hint.

[tomchristie]

Could we avoid adding this API as part of the pull request?

[tducret]

Here, I wanted to preserve this responsibility of raising the KeyError exception to the __getitem__() method.

However, if it's safe to raise it whenever it's not found through get(), then we could remove raise_when_not_found parameter.

What do you think?

[tomchristie]

It's not absolutely clear to me that allowing None here is an API improvement. 🤔

[tducret]

I changed the test to assert cookies["no-value"] is None.
I also added test_get_missing_cookie_raises_exception to highlight the difference between getting a missing cookie (raises exception) and getting a cookie whose value is None.

Is it better?