email stubtest exceptions (#5207)

stdlib/email/_header_value_parser.pyi

@@ -0,0 +1,411 @@
+import sys
+from email.errors import HeaderParseError, MessageDefect
+from email.policy import Policy
+from typing import Any, Iterable, Iterator, List, Optional, Pattern, Set, Tuple, Type, TypeVar, Union
+from typing_extensions import Final
+
+_T = TypeVar("_T")
+
+WSP: Final[Set[str]] = ...
+CFWS_LEADER: Final[Set[str]] = ...
+SPECIALS: Final[Set[str]] = ...
+ATOM_ENDS: Final[Set[str]] = ...
+DOT_ATOM_ENDS: Final[Set[str]] = ...
+PHRASE_ENDS: Final[Set[str]] = ...
+TSPECIALS: Final[Set[str]] = ...
+TOKEN_ENDS: Final[Set[str]] = ...
+ASPECIALS: Final[Set[str]] = ...
+ATTRIBUTE_ENDS: Final[Set[str]] = ...
+EXTENDED_ATTRIBUTE_ENDS: Final[Set[str]] = ...
+
+def quote_string(value: Any) -> str: ...
+
+if sys.version_info >= (3, 7):
+    rfc2047_matcher: Pattern[str]
+
+class TokenList(List[Union[TokenList, Terminal]]):
+    token_type: Optional[str] = ...
+    syntactic_break: bool = ...
+    ew_combine_allowed: bool = ...
+    defects: List[MessageDefect] = ...
+    def __init__(self, *args: Any, **kw: Any) -> None: ...
+    @property
+    def value(self) -> str: ...
+    @property
+    def all_defects(self) -> List[MessageDefect]: ...
+    def startswith_fws(self) -> bool: ...
+    @property
+    def as_ew_allowed(self) -> bool: ...
+    @property
+    def comments(self) -> List[str]: ...
+    def fold(self, *, policy: Policy) -> str: ...
+    def pprint(self, indent: str = ...) -> None: ...
+    def ppstr(self, indent: str = ...) -> str: ...
+
+class WhiteSpaceTokenList(TokenList):
+    @property
+    def value(self) -> str: ...
+    @property
+    def comments(self) -> List[str]: ...
+
+class UnstructuredTokenList(TokenList):
+    token_type: str = ...
+
+class Phrase(TokenList):
+    token_type: str = ...
+
+class Word(TokenList):
+    token_type: str = ...
+
+class CFWSList(WhiteSpaceTokenList):
+    token_type: str = ...
+
+class Atom(TokenList):
+    token_type: str = ...
+
+class Token(TokenList):
+    token_type: str = ...
+    encode_as_ew: bool = ...
+
+class EncodedWord(TokenList):
+    token_type: str = ...
+    cte: Optional[str] = ...
+    charset: Optional[str] = ...
+    lang: Optional[str] = ...
+
+class QuotedString(TokenList):
+    token_type: str = ...
+    @property
+    def content(self) -> str: ...
+    @property
+    def quoted_value(self) -> str: ...
+    @property
+    def stripped_value(self) -> str: ...
+
+class BareQuotedString(QuotedString):
+    token_type: str = ...
+    @property
+    def value(self) -> str: ...
+
+class Comment(WhiteSpaceTokenList):
+    token_type: str = ...
+    def quote(self, value: Any) -> str: ...
+    @property
+    def content(self) -> str: ...
+    @property
+    def comments(self) -> List[str]: ...
+
+class AddressList(TokenList):
+    token_type: str = ...
+    @property
+    def addresses(self) -> List[Address]: ...
+    @property
+    def mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def all_mailboxes(self) -> List[Mailbox]: ...
+
+class Address(TokenList):
+    token_type: str = ...
+    @property
+    def display_name(self) -> str: ...
+    @property
+    def mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def all_mailboxes(self) -> List[Mailbox]: ...
+
+class MailboxList(TokenList):
+    token_type: str = ...
+    @property
+    def mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def all_mailboxes(self) -> List[Mailbox]: ...
+
+class GroupList(TokenList):
+    token_type: str = ...
+    @property
+    def mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def all_mailboxes(self) -> List[Mailbox]: ...
+
+class Group(TokenList):
+    token_type: str = ...
+    @property
+    def mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def all_mailboxes(self) -> List[Mailbox]: ...
+    @property
+    def display_name(self) -> str: ...
+
+class NameAddr(TokenList):
+    token_type: str = ...
+    @property
+    def display_name(self) -> str: ...
+    @property
+    def local_part(self) -> str: ...
+    @property
+    def domain(self) -> str: ...
+    @property
+    def route(self) -> Optional[List[Domain]]: ...
+    @property
+    def addr_spec(self) -> str: ...
+
+class AngleAddr(TokenList):
+    token_type: str = ...
+    @property
+    def local_part(self) -> str: ...
+    @property
+    def domain(self) -> str: ...
+    @property
+    def route(self) -> Optional[List[Domain]]: ...
+    @property
+    def addr_spec(self) -> str: ...
+
+class ObsRoute(TokenList):
+    token_type: str = ...
+    @property
+    def domains(self) -> List[Domain]: ...
+
+class Mailbox(TokenList):
+    token_type: str = ...
+    @property
+    def display_name(self) -> str: ...
+    @property
+    def local_part(self) -> str: ...
+    @property
+    def domain(self) -> str: ...
+    @property
+    def route(self) -> List[str]: ...
+    @property
+    def addr_spec(self) -> str: ...
+
+class InvalidMailbox(TokenList):
+    token_type: str = ...
+    @property
+    def display_name(self) -> None: ...
+    local_part: None = ...
+    domain: None = ...
+    route: None = ...
+    addr_spec: None = ...
+
+class Domain(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    @property
+    def domain(self) -> str: ...
+
+class DotAtom(TokenList):
+    token_type: str = ...
+
+class DotAtomText(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+
+if sys.version_info >= (3, 8):
+    class NoFoldLiteral(TokenList):
+        token_type: str = ...
+        as_ew_allowed: bool = ...
+
+class AddrSpec(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    @property
+    def local_part(self) -> str: ...
+    @property
+    def domain(self) -> str: ...
+    @property
+    def value(self) -> str: ...
+    @property
+    def addr_spec(self) -> str: ...
+
+class ObsLocalPart(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+
+class DisplayName(Phrase):
+    token_type: str = ...
+    ew_combine_allowed: bool = ...
+    @property
+    def display_name(self) -> str: ...
+    @property
+    def value(self) -> str: ...
+
+class LocalPart(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    @property
+    def value(self) -> str: ...
+    @property
+    def local_part(self) -> str: ...
+
+class DomainLiteral(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    @property
+    def domain(self) -> str: ...
+    @property
+    def ip(self) -> str: ...
+
+class MIMEVersion(TokenList):
+    token_type: str = ...
+    major: Optional[int] = ...
+    minor: Optional[int] = ...
+
+class Parameter(TokenList):
+    token_type: str = ...
+    sectioned: bool = ...
+    extended: bool = ...
+    charset: str = ...
+    @property
+    def section_number(self) -> int: ...
+    @property
+    def param_value(self) -> str: ...
+
+class InvalidParameter(Parameter):
+    token_type: str = ...
+
+class Attribute(TokenList):
+    token_type: str = ...
+    @property
+    def stripped_value(self) -> str: ...
+
+class Section(TokenList):
+    token_type: str = ...
+    number: Optional[int] = ...
+
+class Value(TokenList):
+    token_type: str = ...
+    @property
+    def stripped_value(self) -> str: ...
+
+class MimeParameters(TokenList):
+    token_type: str = ...
+    syntactic_break: bool = ...
+    @property
+    def params(self) -> Iterator[Tuple[str, str]]: ...
+
+class ParameterizedHeaderValue(TokenList):
+    syntactic_break: bool = ...
+    @property
+    def params(self) -> Iterable[Tuple[str, str]]: ...
+
+class ContentType(ParameterizedHeaderValue):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    maintype: str = ...
+    subtype: str = ...
+
+class ContentDisposition(ParameterizedHeaderValue):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    content_disposition: Any = ...
+
+class ContentTransferEncoding(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+    cte: str = ...
+
+class HeaderLabel(TokenList):
+    token_type: str = ...
+    as_ew_allowed: bool = ...
+
+if sys.version_info >= (3, 8):
+    class MsgID(TokenList):
+        token_type: str = ...
+        as_ew_allowed: bool = ...
+        def fold(self, policy: Policy) -> str: ...
+    class MessageID(MsgID):
+        token_type: str = ...
+    class InvalidMessageID(MessageID):
+        token_type: str = ...
+
+class Header(TokenList):
+    token_type: str = ...
+
+class Terminal(str):
+    as_ew_allowed: bool = ...
+    ew_combine_allowed: bool = ...
+    syntactic_break: bool = ...
+    token_type: str = ...
+    defects: List[MessageDefect] = ...
+    def __new__(cls: Type[_T], value: str, token_type: str) -> _T: ...
+    def pprint(self) -> None: ...
+    @property
+    def all_defects(self) -> List[MessageDefect]: ...
+    def pop_trailing_ws(self) -> None: ...
+    @property
+    def comments(self) -> List[str]: ...
+    def __getnewargs__(self) -> Tuple[str, str]: ...  # type: ignore
+
+class WhiteSpaceTerminal(Terminal):
+    @property
+    def value(self) -> str: ...
+    def startswith_fws(self) -> bool: ...
+
+class ValueTerminal(Terminal):
+    @property
+    def value(self) -> ValueTerminal: ...
+    def startswith_fws(self) -> bool: ...
+
+class EWWhiteSpaceTerminal(WhiteSpaceTerminal):
+    @property
+    def value(self) -> str: ...
+
+class _InvalidEwError(HeaderParseError): ...
+
+DOT: Final[ValueTerminal]
+ListSeparator: Final[ValueTerminal]
+RouteComponentMarker: Final[ValueTerminal]
+
+def get_fws(value: str) -> Tuple[WhiteSpaceTerminal, str]: ...
+def get_encoded_word(value: str) -> Tuple[EncodedWord, str]: ...
+def get_unstructured(value: str) -> UnstructuredTokenList: ...
+def get_qp_ctext(value: str) -> Tuple[WhiteSpaceTerminal, str]: ...
+def get_qcontent(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_atext(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_bare_quoted_string(value: str) -> Tuple[BareQuotedString, str]: ...
+def get_comment(value: str) -> Tuple[Comment, str]: ...
+def get_cfws(value: str) -> Tuple[CFWSList, str]: ...
+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_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]: ...
+def get_dtext(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_domain_literal(value: str) -> Tuple[DomainLiteral, str]: ...
+def get_domain(value: str) -> Tuple[Domain, str]: ...
+def get_addr_spec(value: str) -> Tuple[AddrSpec, str]: ...
+def get_obs_route(value: str) -> Tuple[ObsRoute, str]: ...
+def get_angle_addr(value: str) -> Tuple[AngleAddr, str]: ...
+def get_display_name(value: str) -> Tuple[DisplayName, str]: ...
+def get_name_addr(value: str) -> Tuple[NameAddr, str]: ...
+def get_mailbox(value: str) -> Tuple[Mailbox, str]: ...
+def get_invalid_mailbox(value: str, endchars: str) -> Tuple[InvalidMailbox, str]: ...
+def get_mailbox_list(value: str) -> Tuple[MailboxList, str]: ...
+def get_group_list(value: str) -> Tuple[GroupList, str]: ...
+def get_group(value: str) -> Tuple[Group, str]: ...
+def get_address(value: str) -> Tuple[Address, str]: ...
+def get_address_list(value: str) -> Tuple[AddressList, str]: ...
+
+if sys.version_info >= (3, 8):
+    def get_no_fold_literal(value: str) -> Tuple[NoFoldLiteral, str]: ...
+    def get_msg_id(value: str) -> Tuple[MsgID, str]: ...
+    def parse_message_id(value: str) -> MessageID: ...
+
+def parse_mime_version(value: str) -> MIMEVersion: ...
+def get_invalid_parameter(value: str) -> Tuple[InvalidParameter, str]: ...
+def get_ttext(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_token(value: str) -> Tuple[Token, str]: ...
+def get_attrtext(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_attribute(value: str) -> Tuple[Attribute, str]: ...
+def get_extended_attrtext(value: str) -> Tuple[ValueTerminal, str]: ...
+def get_extended_attribute(value: str) -> Tuple[Attribute, str]: ...
+def get_section(value: str) -> Tuple[Section, str]: ...
+def get_value(value: str) -> Tuple[Value, str]: ...
+def get_parameter(value: str) -> Tuple[Parameter, str]: ...
+def parse_mime_parameters(value: str) -> MimeParameters: ...
+def parse_content_type_header(value: str) -> ContentType: ...
+def parse_content_disposition_header(value: str) -> ContentDisposition: ...
+def parse_content_transfer_encoding_header(value: str) -> ContentTransferEncoding: ...

stdlib/email/errors.pyi

@@ -1,9 +1,14 @@
+from typing import Optional
+
 class MessageError(Exception): ...
 class MessageParseError(MessageError): ...
 class HeaderParseError(MessageParseError): ...
 class BoundaryError(MessageParseError): ...
 class MultipartConversionError(MessageError, TypeError): ...
-class MessageDefect(ValueError): ...
+
+class MessageDefect(ValueError):
+    def __init__(self, line: Optional[str] = ...) -> None: ...
+
 class NoBoundaryInMultipartDefect(MessageDefect): ...
 class StartBoundaryNotFoundDefect(MessageDefect): ...
 class FirstHeaderLineIsContinuationDefect(MessageDefect): ...

stdlib/email/generator.pyi

@@ -5,14 +5,36 @@ from typing import BinaryIO, Optional, TextIO
 class Generator:
     def clone(self, fp: TextIO) -> Generator: ...
     def write(self, s: str) -> None: ...
-    def __init__(self, outfp: TextIO, mangle_from_: bool = ..., maxheaderlen: int = ..., *, policy: Policy = ...) -> None: ...
+    def __init__(
+        self,
+        outfp: TextIO,
+        mangle_from_: Optional[bool] = ...,
+        maxheaderlen: Optional[int] = ...,
+        *,
+        policy: Optional[Policy] = ...,
+    ) -> None: ...
     def flatten(self, msg: Message, unixfrom: bool = ..., linesep: Optional[str] = ...) -> None: ...
 
 class BytesGenerator:
     def clone(self, fp: BinaryIO) -> BytesGenerator: ...
     def write(self, s: str) -> None: ...
-    def __init__(self, outfp: BinaryIO, mangle_from_: bool = ..., maxheaderlen: int = ..., *, policy: Policy = ...) -> None: ...
+    def __init__(
+        self,
+        outfp: BinaryIO,
+        mangle_from_: Optional[bool] = ...,
+        maxheaderlen: Optional[int] = ...,
+        *,
+        policy: Optional[Policy] = ...,
+    ) -> None: ...
     def flatten(self, msg: Message, unixfrom: bool = ..., linesep: Optional[str] = ...) -> None: ...
 
 class DecodedGenerator(Generator):
-    def __init__(self, outfp: TextIO, mangle_from_: bool = ..., maxheaderlen: int = ..., *, fmt: Optional[str] = ...) -> None: ...
+    def __init__(
+        self,
+        outfp: TextIO,
+        mangle_from_: Optional[bool] = ...,
+        maxheaderlen: Optional[int] = ...,
+        fmt: Optional[str] = ...,
+        *,
+        policy: Optional[Policy] = ...,
+    ) -> None: ...

stdlib/email/headerregistry.pyi

@@ -1,7 +1,17 @@
+import sys
 from datetime import datetime as _datetime
+from email._header_value_parser import (
+    AddressList,
+    ContentDisposition,
+    ContentTransferEncoding,
+    ContentType,
+    MIMEVersion,
+    TokenList,
+    UnstructuredTokenList,
+)
 from email.errors import MessageDefect
 from email.policy import Policy
-from typing import Any, Dict, Iterable, Mapping, Optional, Tuple, Union
+from typing import Any, Dict, Iterable, Mapping, Optional, Tuple, Type, Union
 
 class BaseHeader(str):
     @property
@@ -11,27 +21,36 @@ class BaseHeader(str):
     @property
     def max_count(self) -> Optional[int]: ...
     def __new__(cls, name: str, value: Any) -> BaseHeader: ...
-    def init(self, *args: Any, **kw: Any) -> None: ...
+    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect]) -> None: ...
     def fold(self, *, policy: Policy) -> str: ...
 
 class UnstructuredHeader:
+    @staticmethod
+    def value_parser(value: str) -> UnstructuredTokenList: ...
     @classmethod
-    def parse(cls, string: str, kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
 
 class UniqueUnstructuredHeader(UnstructuredHeader): ...
 
 class DateHeader:
-    datetime: _datetime
+    @property
+    def datetime(self) -> _datetime: ...
+    @staticmethod
+    def value_parser(value: str) -> UnstructuredTokenList: ...
     @classmethod
-    def parse(cls, string: Union[str, _datetime], kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: Union[str, _datetime], kwds: Dict[str, Any]) -> None: ...
 
 class UniqueDateHeader(DateHeader): ...
 
 class AddressHeader:
-    groups: Tuple[Group, ...]
-    addresses: Tuple[Address, ...]
+    @property
+    def groups(self) -> Tuple[Group, ...]: ...
+    @property
+    def addresses(self) -> Tuple[Address, ...]: ...
+    @staticmethod
+    def value_parser(value: str) -> AddressList: ...
     @classmethod
-    def parse(cls, string: str, kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
 
 class UniqueAddressHeader(AddressHeader): ...
 
@@ -42,40 +61,70 @@ class SingleAddressHeader(AddressHeader):
 class UniqueSingleAddressHeader(SingleAddressHeader): ...
 
 class MIMEVersionHeader:
-    version: Optional[str]
-    major: Optional[int]
-    minor: Optional[int]
+    @property
+    def version(self) -> Optional[str]: ...
+    @property
+    def major(self) -> Optional[int]: ...
+    @property
+    def minor(self) -> Optional[int]: ...
+    @staticmethod
+    def value_parser(value: str) -> MIMEVersion: ...
     @classmethod
-    def parse(cls, string: str, kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
 
 class ParameterizedMIMEHeader:
-    params: Mapping[str, Any]
+    @property
+    def params(self) -> Mapping[str, Any]: ...
     @classmethod
-    def parse(cls, string: str, kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
 
 class ContentTypeHeader(ParameterizedMIMEHeader):
-    content_type: str
-    maintype: str
-    subtype: str
+    @property
+    def content_type(self) -> str: ...
+    @property
+    def maintype(self) -> str: ...
+    @property
+    def subtype(self) -> str: ...
+    @staticmethod
+    def value_parser(value: str) -> ContentType: ...
 
 class ContentDispositionHeader(ParameterizedMIMEHeader):
-    content_disposition: str
+    @property
+    def content_disposition(self) -> str: ...
+    @staticmethod
+    def value_parser(value: str) -> ContentDisposition: ...
 
 class ContentTransferEncodingHeader:
-    cte: str
+    @property
+    def cte(self) -> str: ...
     @classmethod
-    def parse(cls, string: str, kwds: Dict[str, Any]) -> None: ...
+    def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
+    @staticmethod
+    def value_parser(value: str) -> ContentTransferEncoding: ...
+
+if sys.version_info >= (3, 8):
+    from email._header_value_parser import MessageID
+    class MessageIDHeader:
+        @classmethod
+        def parse(cls, value: str, kwds: Dict[str, Any]) -> None: ...
+        @staticmethod
+        def value_parser(value: str) -> MessageID: ...
 
 class HeaderRegistry:
-    def __init__(self, base_class: BaseHeader = ..., default_class: BaseHeader = ..., use_default_map: bool = ...) -> None: ...
-    def map_to_type(self, name: str, cls: BaseHeader) -> None: ...
-    def __getitem__(self, name: str) -> BaseHeader: ...
+    def __init__(
+        self, base_class: Type[BaseHeader] = ..., default_class: Type[BaseHeader] = ..., use_default_map: bool = ...
+    ) -> 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: ...
 
 class Address:
-    display_name: str
-    username: str
-    domain: str
+    @property
+    def display_name(self) -> str: ...
+    @property
+    def username(self) -> str: ...
+    @property
+    def domain(self) -> str: ...
     @property
     def addr_spec(self) -> str: ...
     def __init__(
@@ -84,7 +133,9 @@ class Address:
     def __str__(self) -> str: ...
 
 class Group:
-    display_name: Optional[str]
-    addresses: Tuple[Address, ...]
+    @property
+    def display_name(self) -> Optional[str]: ...
+    @property
+    def addresses(self) -> Tuple[Address, ...]: ...
     def __init__(self, display_name: Optional[str] = ..., addresses: Optional[Iterable[Address]] = ...) -> None: ...
     def __str__(self) -> str: ...

stdlib/email/message.pyi

@@ -22,7 +22,7 @@ class Message:
     def set_unixfrom(self, unixfrom: str) -> None: ...
     def get_unixfrom(self) -> Optional[str]: ...
     def attach(self, payload: Message) -> None: ...
-    def get_payload(self, i: int = ..., decode: bool = ...) -> Any: ...  # returns Optional[_PayloadType]
+    def get_payload(self, i: Optional[int] = ..., decode: bool = ...) -> Any: ...  # returns Optional[_PayloadType]
     def set_payload(self, payload: _PayloadType, charset: _CharsetType = ...) -> None: ...
     def set_charset(self, charset: _CharsetType) -> None: ...
     def get_charset(self) -> _CharsetType: ...
@@ -63,13 +63,14 @@ class Message:
         value: str,
         header: str = ...,
         requote: bool = ...,
-        charset: str = ...,
+        charset: Optional[str] = ...,
         language: str = ...,
         replace: bool = ...,
     ) -> None: ...
     def __init__(self, policy: Policy = ...) -> None: ...
 
 class MIMEPart(Message):
+    def __init__(self, policy: Optional[Policy] = ...) -> None: ...
     def get_body(self, preferencelist: Sequence[str] = ...) -> Optional[Message]: ...
     def iter_attachments(self) -> Iterator[Message]: ...
     def iter_parts(self) -> Iterator[Message]: ...
@@ -83,6 +84,7 @@ class MIMEPart(Message):
     def add_attachment(self, *args: Any, content_manager: Optional[ContentManager] = ..., **kw: Any) -> None: ...
     def clear(self) -> None: ...
     def clear_content(self) -> None: ...
+    def as_string(self, unixfrom: bool = ..., maxheaderlen: Optional[int] = ..., policy: Optional[Policy] = ...) -> str: ...
     def is_attachment(self) -> bool: ...
 
 class EmailMessage(MIMEPart): ...

stdlib/email/parser.pyi

@@ -1,18 +1,18 @@
 import email.feedparser
 from email.message import Message
 from email.policy import Policy
-from typing import BinaryIO, Callable, TextIO
+from typing import BinaryIO, Callable, Optional, TextIO
 
 FeedParser = email.feedparser.FeedParser
 BytesFeedParser = email.feedparser.BytesFeedParser
 
 class Parser:
-    def __init__(self, _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> None: ...
+    def __init__(self, _class: Optional[Callable[[], Message]] = ..., *, policy: Policy = ...) -> None: ...
     def parse(self, fp: TextIO, headersonly: bool = ...) -> Message: ...
     def parsestr(self, text: str, headersonly: bool = ...) -> Message: ...
 
 class HeaderParser(Parser):
-    def __init__(self, _class: Callable[[], Message] = ..., *, policy: Policy = ...) -> None: ...
+    def __init__(self, _class: Optional[Callable[[], Message]] = ..., *, policy: Policy = ...) -> None: ...
     def parse(self, fp: TextIO, headersonly: bool = ...) -> Message: ...
     def parsestr(self, text: str, headersonly: bool = ...) -> Message: ...
 

stdlib/email/utils.pyi

@@ -8,31 +8,31 @@ _PDTZ = Tuple[int, int, int, int, int, int, int, int, int, Optional[int]]
 
 def quote(str: str) -> str: ...
 def unquote(str: str) -> str: ...
-def parseaddr(address: Optional[str]) -> Tuple[str, str]: ...
+def parseaddr(addr: Optional[str]) -> Tuple[str, str]: ...
 def formataddr(pair: Tuple[Optional[str], str], charset: Union[str, Charset] = ...) -> str: ...
 def getaddresses(fieldvalues: List[str]) -> List[Tuple[str, str]]: ...
 @overload
-def parsedate(date: None) -> None: ...
+def parsedate(data: None) -> None: ...
 @overload
-def parsedate(date: str) -> Optional[Tuple[int, int, int, int, int, int, int, int, int]]: ...
+def parsedate(data: str) -> Optional[Tuple[int, int, int, int, int, int, int, int, int]]: ...
 @overload
-def parsedate_tz(date: None) -> None: ...
+def parsedate_tz(data: None) -> None: ...
 @overload
-def parsedate_tz(date: str) -> Optional[_PDTZ]: ...
+def parsedate_tz(data: str) -> Optional[_PDTZ]: ...
 
 if sys.version_info >= (3, 10):
     @overload
-    def parsedate_to_datetime(date: None) -> None: ...
+    def parsedate_to_datetime(data: None) -> None: ...
     @overload
-    def parsedate_to_datetime(date: str) -> datetime.datetime: ...
+    def parsedate_to_datetime(data: str) -> datetime.datetime: ...
 
 else:
-    def parsedate_to_datetime(date: str) -> datetime.datetime: ...
+    def parsedate_to_datetime(data: str) -> datetime.datetime: ...
 
-def mktime_tz(tuple: _PDTZ) -> int: ...
+def mktime_tz(data: _PDTZ) -> int: ...
 def formatdate(timeval: Optional[float] = ..., localtime: bool = ..., usegmt: bool = ...) -> str: ...
 def format_datetime(dt: datetime.datetime, usegmt: bool = ...) -> str: ...
-def localtime(dt: Optional[datetime.datetime] = ...) -> datetime.datetime: ...
+def localtime(dt: Optional[datetime.datetime] = ..., isdst: int = ...) -> datetime.datetime: ...
 def make_msgid(idstring: Optional[str] = ..., domain: Optional[str] = ...) -> str: ...
 def decode_rfc2231(s: str) -> Tuple[Optional[str], Optional[str], str]: ...
 def encode_rfc2231(s: str, charset: Optional[str] = ..., language: Optional[str] = ...) -> str: ...

tests/stubtest_whitelists/py36.txt

@@ -21,7 +21,6 @@ collections.AsyncGenerator.ag_running
 collections.UserString.maketrans
 contextlib._GeneratorContextManager.__init__
 copy.PyStringMap
-email.message.MIMEPart.as_string
 enum.Enum._generate_next_value_
 fractions.Fraction.__new__  # overload is too complicated for stubtest to resolve
 hmac.HMAC.__init__

tests/stubtest_whitelists/py37.txt

@@ -31,7 +31,6 @@ contextvars.ContextVar.get
 contextlib.nullcontext  # not a function at runtime
 copy.PyStringMap
 dataclasses.field
-email.message.MIMEPart.as_string
 enum.Enum._generate_next_value_
 fractions.Fraction.__new__  # overload is too complicated for stubtest to resolve
 hmac.HMAC.__init__

tests/stubtest_whitelists/py38.txt

@@ -46,7 +46,6 @@ copy.PyStringMap
 # This was changed in Python 3.8.8.
 curses.color_pair
 dataclasses.field
-email.message.MIMEPart.as_string
 enum.Enum._generate_next_value_
 fractions.Fraction.__new__  # overload is too complicated for stubtest to resolve
 functools.partialmethod.__get__

tests/stubtest_whitelists/py39.txt

@@ -53,7 +53,6 @@ curses.color_pair
 dataclasses.field
 dataclasses.InitVar.__class_getitem__  # stubtest bug. doesn't do the right thing with overload + implicit classmethod __class_getitem__
 dummy_threading
-email.message.MIMEPart.as_string
 enum.Enum._generate_next_value_
 fractions.Fraction.__new__  # overload is too complicated for stubtest to resolve
 ftplib.FTP.__init__

tests/stubtest_whitelists/py3_common.txt

@@ -139,30 +139,7 @@ difflib.SequenceMatcher.__init__  # mypy default value for generic parameter iss
 distutils.command.bdist_packager  # It exists in docs as package name but not in code except as a mention in a comment.
 distutils.version.Version._cmp  # class should have declared this
 distutils.version.Version.parse  # class should have declared this
-email.errors.MessageDefect.__init__
-email.generator.BytesGenerator.__init__
-email.generator.DecodedGenerator.__init__
-email.generator.Generator.__init__
-email.headerregistry.AddressHeader.parse
-email.headerregistry.BaseHeader.init
-email.headerregistry.BaseHeader.max_count
-email.headerregistry.ContentTransferEncodingHeader.parse
-email.headerregistry.DateHeader.parse
-email.headerregistry.HeaderRegistry.__init__
-email.headerregistry.MIMEVersionHeader.parse
-email.headerregistry.ParameterizedMIMEHeader.parse
-email.headerregistry.UnstructuredHeader.parse
-email.message.MIMEPart.__init__
-email.message.Message.get_payload
-email.message.Message.set_param
-email.parser.HeaderParser.__init__
-email.parser.Parser.__init__
-email.utils.localtime
-email.utils.mktime_tz
-email.utils.parseaddr
-email.utils.parsedate
-email.utils.parsedate_to_datetime
-email.utils.parsedate_tz
+email.headerregistry.BaseHeader.max_count  # docs say subclasses should have this property
 encodings.utf_8.IncrementalDecoder._buffer_decode
 encodings.utf_8.StreamReader.decode
 encodings.utf_8.StreamWriter.encode