fix: correct headers= kwarg in HTTP[S]Connection

[dimaqq]

I've found code in the library that in a nutshell did this:

headers = {}
headers["Content-Length"] = len(data)

an_https_connection.request("PUT", url, data, headers)

And the type checker was not happy about an int as a header value.
Apparently Python stdlib allows:

• anything with .encode("ascii") since Python 3.0
• an int, explicitly, at least since Python 3.2
• anything that can be passed to bytes.join, which is a ReadableBuffer in typeshed

References:

https://github.com/python/cpython/blob/v3.0/Lib/http/client.py
https://github.com/python/cpython/blob/6046c5e0298c25515ea58abc8ab87f7413e3f743/Lib/http/client.py#L831-L834

https://github.com/python/cpython/blob/3.2/Lib/http/client.py
https://github.com/python/cpython/blob/076ca6c3c8df3030307e548d9be792ce3c1c6eea/Lib/http/client.py#L961-L966

[dimaqq]

Would someone help me with advice here?

I'm wondering if perhaps explicitly adding str | bytes | ... to the list would help with the urllib3 override, because then the override uses a narrower type?

Or is this a catch-22, we can't enlarge the superclass type, because the subclass may be unprepared for the extra type, in case the end user receives a subclass instance typed as superclass?

[srittau]

Thanks! You can ignore the primer output. The urllib3 project just needs to update their annotations (or ignore the override).

You could consider just leaving str instead of using a protocol. This leads to cleaner error output, clearer annotations, and is easier to subclass. The protocol is tighter, but I'm not sure it matters in practice. I'll accept whatever you prefer.

[dimaqq]

Updated.

I wonder what brings more value, ReadableBuffer or just bytes?

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

urllib3 (https://github.com/urllib3/urllib3)
+ src/urllib3/http2/connection.py:143: error: Signature of "putheader" incompatible with supertype "HTTPConnection"  [override]
+ src/urllib3/http2/connection.py:143: note:      Superclass:
+ src/urllib3/http2/connection.py:143: note:          def putheader(self, header: str | bytes, *values: Buffer | str | int) -> None
+ src/urllib3/http2/connection.py:143: note:      Subclass:
+ src/urllib3/http2/connection.py:143: note:          def putheader(self, header: str | bytes, *values: str | bytes) -> None