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

stdlib/email/__init__.pyi

@@ -1,7 +1,7 @@
 from collections.abc import Callable
 from email.message import Message
-from email.policy import Policy
-from typing import IO
+from email.policy import Policy, _MessageT
+from typing import IO, overload
 from typing_extensions import TypeAlias
 
 # At runtime, listing submodules in __all__ without them being imported is
@@ -31,7 +31,29 @@ __all__ = [  # noqa: F822  # Undefined names in __all__
 _ParamType: TypeAlias = str | tuple[str | None, str | None, str]  # noqa: Y047
 _ParamsType: TypeAlias = str | None | tuple[str, str | None, str]  # noqa: Y047
 
-def message_from_string(s: str, _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> Message: ...
-def message_from_bytes(s: bytes | bytearray, _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> Message: ...
-def message_from_file(fp: IO[str], _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> Message: ...
-def message_from_binary_file(fp: IO[bytes], _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> Message: ...
+@overload
+def message_from_string(s: str) -> Message: ...
+@overload
+def message_from_string(s: str, _class: Callable[[], _MessageT]) -> _MessageT: ...
+@overload
+def message_from_string(s: str, _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]) -> _MessageT: ...
+@overload
+def message_from_bytes(s: bytes | bytearray) -> Message: ...
+@overload
+def message_from_bytes(s: bytes | bytearray, _class: Callable[[], _MessageT]) -> _MessageT: ...
+@overload
+def message_from_bytes(
+    s: bytes | bytearray, _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]
+) -> _MessageT: ...
+@overload
+def message_from_file(fp: IO[str]) -> Message: ...
+@overload
+def message_from_file(fp: IO[str], _class: Callable[[], _MessageT]) -> _MessageT: ...
+@overload
+def message_from_file(fp: IO[str], _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]) -> _MessageT: ...
+@overload
+def message_from_binary_file(fp: IO[bytes]) -> Message: ...
+@overload
+def message_from_binary_file(fp: IO[bytes], _class: Callable[[], _MessageT]) -> _MessageT: ...
+@overload
+def message_from_binary_file(fp: IO[bytes], _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]) -> _MessageT: ...

stdlib/email/mime/message.pyi

@@ -1,8 +1,7 @@
-from email.message import Message
 from email.mime.nonmultipart import MIMENonMultipart
-from email.policy import Policy
+from email.policy import Policy, _MessageT
 
 __all__ = ["MIMEMessage"]
 
 class MIMEMessage(MIMENonMultipart):
-    def __init__(self, _msg: Message, _subtype: str = "rfc822", *, policy: Policy | None = None) -> None: ...
+    def __init__(self, _msg: _MessageT, _subtype: str = "rfc822", *, policy: Policy[_MessageT] | None = None) -> None: ...

stdlib/email/mime/multipart.pyi

@@ -1,8 +1,7 @@
 from collections.abc import Sequence
 from email import _ParamsType
-from email.message import Message
 from email.mime.base import MIMEBase
-from email.policy import Policy
+from email.policy import Policy, _MessageT
 
 __all__ = ["MIMEMultipart"]
 
@@ -11,8 +10,8 @@ class MIMEMultipart(MIMEBase):
         self,
         _subtype: str = "mixed",
         boundary: str | None = None,
-        _subparts: Sequence[Message] | None = None,
+        _subparts: Sequence[_MessageT] | None = None,
         *,
-        policy: Policy | None = None,
+        policy: Policy[_MessageT] | None = None,
         **_params: _ParamsType,
     ) -> None: ...