Make various email.Policy use sites generic over the message type

[brianschubert]

Fixes #13273

email.Policy was made generic in #12724. A bunch of places where its used don't provide an explicit type argument and use the default argument of Message. However, since email.Policy is invariant in the message type, this causes problems when trying to pass Policy instances that use subtypes of Message.

This PR makes various places where email.Policy is used generic in the message type, allowing the message type to be inferred instead of always defaulting to Message.

For context:

import email.policy

>>> email.message_from_string("")
<email.message.Message object at 0x7d3bf00c2410>

>>> email.message_from_string("", policy=email.policy.default)
<email.message.EmailMessage object at 0x7d3bf00c24d0>  # <-- message type determined by policy

>>> email.message_from_string("", email.message.EmailMessage)
<email.message.EmailMessage object at 0x7d3bf00c25c0>  # <-- message type determined by _class

[brianschubert]

The overloads in email/__init__.pyi are needed to satisfy pyright. Mypy supports using the type variable default when no arguments are provided, but pyright does not. PEP 696 gives type checkers the freedom to either support this or not, so neither behavior is incorrect.

[dseomn]

I just started getting a mypy error that I think is caused by the same issue, but it doesn't look like this PR touches email.parser.BytesParser at all. Would it make sense to change that in this PR too? Or should I file a separate bug?

Error:

rock_paper_sand/report_test.py:465: error: Argument "policy" to "BytesParser" has incompatible type "EmailPolicy[EmailMessage]"; expected "Policy[Message[str, str]]"  [arg-type]

Code:

        message = typing.cast(
            email.message.EmailMessage,
            email.parser.BytesParser(policy=email.policy.default).parsebytes(
                mock_subprocess_run.mock_calls[0].kwargs["input"]
            ),
        )

[cossor]

mypy 1.15.0 also complains about parser.Parser(policy=policy.default) so i continue to use 1.13.0 and changed my code to use message_from_string in anticipation of this PR's deployment. happy to see more commits, but merging this PR as-is would be a step in the right direction.

Le mieux est l'ennemi du bien.

[srittau]

Thanks!

[github-actions]

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