[email] Various improvements

pyrightconfig.stricter.json

@@ -14,6 +14,7 @@
         "stdlib/distutils/cmd.pyi",
         "stdlib/distutils/command",
         "stdlib/distutils/dist.pyi",
+        "stdlib/email/*.pyi",
         "stdlib/encodings/__init__.pyi",
         "stdlib/lib2to3/fixes/*.pyi",
         "stdlib/numbers.pyi",

stdlib/email/__init__.pyi

@@ -1,8 +1,10 @@
+from _typeshed import SupportsRead
 from collections.abc import Callable
 from email._policybase import _MessageT
 from email.message import Message
 from email.policy import Policy
-from typing import IO, TypeAlias, overload
+from io import _WrappedBuffer
+from typing import TypeAlias, overload
 
 # At runtime, listing submodules in __all__ without them being imported is
 # valid, and causes them to be included in a star import. See #6523
@@ -32,14 +34,14 @@ _ParamType: TypeAlias = str | tuple[str | None, str | None, str]  # noqa: Y047
 _ParamsType: TypeAlias = str | None | tuple[str, str | None, str]  # noqa: Y047
 
 @overload
-def message_from_string(s: str) -> Message: ...
+def message_from_string(s: str) -> Message[str, str]: ...
 @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: ...
+def message_from_bytes(s: bytes | bytearray) -> Message[str, str]: ...
 @overload
 def message_from_bytes(s: bytes | bytearray, _class: Callable[[], _MessageT]) -> _MessageT: ...
 @overload
@@ -48,15 +50,19 @@ def message_from_bytes(
 ) -> _MessageT: ...
 
 @overload
-def message_from_file(fp: IO[str]) -> Message: ...
+def message_from_file(fp: SupportsRead[str]) -> Message[str, str]: ...
 @overload
-def message_from_file(fp: IO[str], _class: Callable[[], _MessageT]) -> _MessageT: ...
+def message_from_file(fp: SupportsRead[str], _class: Callable[[], _MessageT]) -> _MessageT: ...
 @overload
-def message_from_file(fp: IO[str], _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]) -> _MessageT: ...
+def message_from_file(
+    fp: SupportsRead[str], _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]
+) -> _MessageT: ...
 
 @overload
-def message_from_binary_file(fp: IO[bytes]) -> Message: ...
+def message_from_binary_file(fp: _WrappedBuffer) -> Message[str, str]: ...
 @overload
-def message_from_binary_file(fp: IO[bytes], _class: Callable[[], _MessageT]) -> _MessageT: ...
+def message_from_binary_file(fp: _WrappedBuffer, _class: Callable[[], _MessageT]) -> _MessageT: ...
 @overload
-def message_from_binary_file(fp: IO[bytes], _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]) -> _MessageT: ...
+def message_from_binary_file(
+    fp: _WrappedBuffer, _class: Callable[[], _MessageT] = ..., *, policy: Policy[_MessageT]
+) -> _MessageT: ...

stdlib/email/_header_value_parser.pyi

@@ -1,9 +1,10 @@
 import sys
+from _typeshed import Incomplete
 from collections.abc import Iterable, Iterator
 from email.errors import HeaderParseError, MessageDefect
 from email.policy import Policy
 from re import Pattern
-from typing import Any, Final
+from typing import Final
 from typing_extensions import Self
 
 WSP: Final[set[str]]
@@ -23,11 +24,11 @@ NLSET: Final[set[str]]
 SPECIALSNL: Final[set[str]]
 
 # Added in Python 3.10.17, 3.11.12, 3.12.9, 3.13.2
-def make_quoted_pairs(value: Any) -> str: ...
-def quote_string(value: Any) -> str: ...
+def make_quoted_pairs(value) -> str: ...
+def quote_string(value) -> str: ...
 
 # Added in Python 3.10.20, 3.11.15, 3.12.13, 3.13.12, 3.14.3
-def make_parenthesis_pairs(value: Any) -> str: ...
+def make_parenthesis_pairs(value) -> str: ...
 
 rfc2047_matcher: Final[Pattern[str]]
 
@@ -36,7 +37,7 @@ class TokenList(list[TokenList | Terminal]):
     syntactic_break: bool
     ew_combine_allowed: bool
     defects: list[MessageDefect]
-    def __init__(self, *args: Any, **kw: Any) -> None: ...
+    def __init__(self, *args, **kw) -> None: ...
     @property
     def value(self) -> str: ...
     @property
@@ -91,7 +92,7 @@ class BareQuotedString(QuotedString):
 
 class Comment(WhiteSpaceTokenList):
     token_type: str
-    def quote(self, value: Any) -> str: ...
+    def quote(self, value) -> str: ...
     @property
     def content(self) -> str: ...
 
@@ -293,7 +294,7 @@ class ContentType(ParameterizedHeaderValue):
 class ContentDisposition(ParameterizedHeaderValue):
     token_type: str
     as_ew_allowed: bool
-    content_disposition: Any
+    content_disposition: Incomplete
 
 class ContentTransferEncoding(TokenList):
     token_type: str
@@ -370,7 +371,7 @@ def get_quoted_string(value: str) -> tuple[QuotedString, str]: ...
 def get_atom(value: str) -> tuple[Atom, str]: ...
 def get_dot_atom_text(value: str) -> tuple[DotAtomText, str]: ...
 def get_dot_atom(value: str) -> tuple[DotAtom, str]: ...
-def get_word(value: str) -> tuple[Any, str]: ...
+def get_word(value: str) -> tuple[Incomplete, str]: ...
 def get_phrase(value: str) -> tuple[Phrase, str]: ...
 def get_local_part(value: str) -> tuple[LocalPart, str]: ...
 def get_obs_local_part(value: str) -> tuple[ObsLocalPart, str]: ...

stdlib/email/contentmanager.pyi

@@ -1,11 +1,11 @@
+from _typeshed import Incomplete
 from collections.abc import Callable
 from email.message import Message
-from typing import Any
 
 class ContentManager:
-    def get_content(self, msg: Message, *args: Any, **kw: Any) -> Any: ...
-    def set_content(self, msg: Message, obj: Any, *args: Any, **kw: Any) -> Any: ...
-    def add_get_handler(self, key: str, handler: Callable[..., Any]) -> None: ...
-    def add_set_handler(self, typekey: type, handler: Callable[..., Any]) -> None: ...
+    def get_content(self, msg: Message, *args, **kw): ...
+    def set_content(self, msg: Message, obj, *args, **kw): ...
+    def add_get_handler(self, key: str, handler: Callable[..., Incomplete]) -> None: ...
+    def add_set_handler(self, typekey: type, handler: Callable[..., Incomplete]) -> None: ...
 
 raw_data_manager: ContentManager

stdlib/email/headerregistry.pyi

@@ -1,5 +1,6 @@
 import sys
 import types
+from _typeshed import Incomplete
 from collections.abc import Iterable, Mapping
 from datetime import datetime as _datetime
 from email._header_value_parser import (
@@ -14,7 +15,7 @@ from email._header_value_parser import (
 )
 from email.errors import MessageDefect
 from email.policy import Policy
-from typing import Any, ClassVar, Literal, Protocol, type_check_only
+from typing import ClassVar, Literal, Protocol, type_check_only
 from typing_extensions import Self
 
 class BaseHeader(str):
@@ -24,7 +25,7 @@ class BaseHeader(str):
     def name(self) -> str: ...
     @property
     def defects(self) -> tuple[MessageDefect, ...]: ...
-    def __new__(cls, name: str, value: Any) -> Self: ...
+    def __new__(cls, name: str, value) -> Self: ...
     def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect]) -> None: ...
     def fold(self, *, policy: Policy) -> str: ...
 
@@ -33,7 +34,7 @@ class UnstructuredHeader:
     @staticmethod
     def value_parser(value: str) -> UnstructuredTokenList: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
 
 class UniqueUnstructuredHeader(UnstructuredHeader):
     max_count: ClassVar[Literal[1]]
@@ -46,7 +47,7 @@ class DateHeader:
     @staticmethod
     def value_parser(value: str) -> UnstructuredTokenList: ...
     @classmethod
-    def parse(cls, value: str | _datetime, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str | _datetime, kwds: dict[str, Incomplete]) -> None: ...
 
 class UniqueDateHeader(DateHeader):
     max_count: ClassVar[Literal[1]]
@@ -61,7 +62,7 @@ class AddressHeader:
     @staticmethod
     def value_parser(value: str) -> AddressList: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
 
 class UniqueAddressHeader(AddressHeader):
     max_count: ClassVar[Literal[1]]
@@ -94,15 +95,17 @@ class MIMEVersionHeader:
     @staticmethod
     def value_parser(value: str) -> MIMEVersion: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
 
 class ParameterizedMIMEHeader:
     max_count: ClassVar[Literal[1]]
-    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect], params: Mapping[str, Any]) -> None: ...
+    def init(
+        self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect], params: Mapping[str, Incomplete]
+    ) -> None: ...
     @property
-    def params(self) -> types.MappingProxyType[str, Any]: ...
+    def params(self) -> types.MappingProxyType[str, Incomplete]: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
 
 class ContentTypeHeader(ParameterizedMIMEHeader):
     @property
@@ -127,14 +130,14 @@ class ContentTransferEncodingHeader:
     @property
     def cte(self) -> str: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
     @staticmethod
     def value_parser(value: str) -> ContentTransferEncoding: ...
 
 class MessageIDHeader:
     max_count: ClassVar[Literal[1]]
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
     @staticmethod
     def value_parser(value: str) -> MessageID: ...
 
@@ -145,7 +148,7 @@ if sys.version_info >= (3, 13):
     class ReferencesHeader:
         max_count: ClassVar[Literal[1]]
         @classmethod
-        def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
+        def parse(cls, value: str, kwds: dict[str, Incomplete]) -> None: ...
         @staticmethod
         def value_parser(value: str) -> MessageIDList: ...
 
@@ -155,7 +158,7 @@ class _HeaderParser(Protocol):
     @staticmethod
     def value_parser(value: str, /) -> TokenList: ...
     @classmethod
-    def parse(cls, value: str, kwds: dict[str, Any], /) -> None: ...
+    def parse(cls, value: str, kwds: dict[str, Incomplete], /) -> None: ...
 
 class HeaderRegistry:
     registry: dict[str, type[_HeaderParser]]
@@ -166,7 +169,7 @@ class HeaderRegistry:
     ) -> None: ...
     def map_to_type(self, name: str, cls: type[BaseHeader]) -> None: ...
     def __getitem__(self, name: str) -> type[BaseHeader]: ...
-    def __call__(self, name: str, value: Any) -> BaseHeader: ...
+    def __call__(self, name: str, value) -> BaseHeader: ...
 
 class Address:
     @property

stdlib/email/message.pyi

@@ -175,14 +175,14 @@ class MIMEPart(Message[_HeaderRegistryT_co, _HeaderRegistryParamT_contra]):
     # cause unforseen consequences.
     def iter_attachments(self) -> Iterator[Self]: ...
     def iter_parts(self) -> Iterator[MIMEPart[_HeaderRegistryT_co, _HeaderRegistryParamT_contra]]: ...
-    def get_content(self, *args: Any, content_manager: ContentManager | None = None, **kw: Any) -> Any: ...
-    def set_content(self, *args: Any, content_manager: ContentManager | None = None, **kw: Any) -> None: ...
+    def get_content(self, *args, content_manager: ContentManager | None = None, **kw): ...
+    def set_content(self, *args, content_manager: ContentManager | None = None, **kw) -> None: ...
     def make_related(self, boundary: str | None = None) -> None: ...
     def make_alternative(self, boundary: str | None = None) -> None: ...
     def make_mixed(self, boundary: str | None = None) -> None: ...
-    def add_related(self, *args: Any, content_manager: ContentManager | None = ..., **kw: Any) -> None: ...
-    def add_alternative(self, *args: Any, content_manager: ContentManager | None = ..., **kw: Any) -> None: ...
-    def add_attachment(self, *args: Any, content_manager: ContentManager | None = ..., **kw: Any) -> None: ...
+    def add_related(self, *args, content_manager: ContentManager | None = ..., **kw) -> None: ...
+    def add_alternative(self, *args, content_manager: ContentManager | None = ..., **kw) -> None: ...
+    def add_attachment(self, *args, content_manager: ContentManager | None = ..., **kw) -> None: ...
     def clear(self) -> None: ...
     def clear_content(self) -> None: ...
     def as_string(self, unixfrom: bool = False, maxheaderlen: int | None = None, policy: Policy[Any] | None = None) -> str: ...

stdlib/email/policy.pyi

@@ -1,57 +1,58 @@
+from _typeshed import Incomplete
 from collections.abc import Callable
 from email._policybase import Compat32 as Compat32, Policy as Policy, _MessageFactory, _MessageT, compat32 as compat32
 from email.contentmanager import ContentManager
 from email.message import EmailMessage
-from typing import Any, overload
+from typing import overload
 from typing_extensions import Self
 
 __all__ = ["Compat32", "compat32", "Policy", "EmailPolicy", "default", "strict", "SMTP", "HTTP"]
 
 class EmailPolicy(Policy[_MessageT]):
     utf8: bool
     refold_source: str
-    header_factory: Callable[[str, Any], Any]
+    header_factory: Callable[[str, Incomplete], Incomplete]
     content_manager: ContentManager
 
     @overload
     def __init__(
         self: EmailPolicy[EmailMessage],
         *,
-        max_line_length: int | None = ...,
-        linesep: str = ...,
-        cte_type: str = ...,
-        raise_on_defect: bool = ...,
-        mangle_from_: bool = ...,
+        max_line_length: int | None = 78,
+        linesep: str = "\n",
+        cte_type: str = "8bit",
+        raise_on_defect: bool = False,
+        mangle_from_: bool = ...,  # default depends on sub-class
         message_factory: None = None,
         # Added in Python 3.9.20, 3.10.15, 3.11.10, 3.12.5
-        verify_generated_headers: bool = ...,
-        utf8: bool = ...,
-        refold_source: str = ...,
+        verify_generated_headers: bool = True,
+        utf8: bool = False,
+        refold_source: str = "long",
         header_factory: Callable[[str, str], str] = ...,
         content_manager: ContentManager = ...,
     ) -> None: ...
     @overload
     def __init__(
         self,
         *,
-        max_line_length: int | None = ...,
-        linesep: str = ...,
-        cte_type: str = ...,
-        raise_on_defect: bool = ...,
-        mangle_from_: bool = ...,
-        message_factory: _MessageFactory[_MessageT] | None = ...,
+        max_line_length: int | None = 78,
+        linesep: str = "\n",
+        cte_type: str = "8bit",
+        raise_on_defect: bool = False,
+        mangle_from_: bool = ...,  # default depends on sub-class
+        message_factory: _MessageFactory[_MessageT],
         # Added in Python 3.9.20, 3.10.15, 3.11.10, 3.12.5
-        verify_generated_headers: bool = ...,
-        utf8: bool = ...,
-        refold_source: str = ...,
+        verify_generated_headers: bool = True,
+        utf8: bool = False,
+        refold_source: str = "long",
         header_factory: Callable[[str, str], str] = ...,
         content_manager: ContentManager = ...,
     ) -> None: ...
 
     def header_source_parse(self, sourcelines: list[str]) -> tuple[str, str]: ...
-    def header_store_parse(self, name: str, value: Any) -> tuple[str, Any]: ...
-    def header_fetch_parse(self, name: str, value: str) -> Any: ...
-    def fold(self, name: str, value: str) -> Any: ...
+    def header_store_parse(self, name: str, value) -> tuple[str, Incomplete]: ...
+    def header_fetch_parse(self, name: str, value: str): ...
+    def fold(self, name: str, value: str): ...
     def fold_binary(self, name: str, value: str) -> bytes: ...
     def clone(
         self,