set session.headers to MutableMapping

[evilensky]

Resolves #9390.

The session.headers may be set to any mapping according to the project, and mutable mapping appears to be the most correct annotation.

[AlexWaygood]

Are you sure this should be MutableMapping[str, str | bytes | None] rather than MutableMapping[str, str | bytes]? This annotation was debated somewhat extensively in #7773 (comment). @janrito said at the time:

We want to allow str or bytes on actual headers, but None only on updates

[evilensky]

No, I am not sure. But given that this code does not produce any runtime error:

session = requests.Session()
session.headers = None
resp = session.get('http://example.com')
assert resp.status_code == 200

It appears headers get merged-or-set-to-defaults with None? https://github.com/psf/requests/blob/main/requests/sessions.py#L61-L71

Edit for clarity: I'm open to any guidance on whether type checking should reflect runtime behavior or do "something else."

[AlexWaygood]

If it's okay to set session.headers to None, then the annotation should be headers: MutableMapping[str, str | bytes] | None rather than MutableMapping[str, str | bytes | None]

[AlexWaygood]

From the mypy_primer output, looks like changing it to MutableMapping[str, str | bytes] | None would be quite disruptive -- so I vote for keeping this as MutableMapping[str, str | bytes] for now, unless keeping it that way is causing a concrete problem for you.

[AlexWaygood]

Thanks @evilensky! Will merge once the CI has finished.

requests is tricky to write stubs for, there's loads of unexpected things that crop up...

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉