Fix and comment type mismatches in email library hints (#10437)

stdlib/email/charset.pyi

@@ -1,4 +1,6 @@
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
+from email.message import Message
+from typing import overload
 
 __all__ = ["Charset", "add_alias", "add_charset", "add_codec"]
 
@@ -14,10 +16,13 @@ class Charset:
     input_codec: str | None
     output_codec: str | None
     def __init__(self, input_charset: str = "us-ascii") -> None: ...
-    def get_body_encoding(self) -> str: ...
+    def get_body_encoding(self) -> str | Callable[[Message], None]: ...
     def get_output_charset(self) -> str | None: ...
     def header_encode(self, string: str) -> str: ...
     def header_encode_lines(self, string: str, maxlengths: Iterator[int]) -> list[str]: ...
+    @overload
+    def body_encode(self, string: None) -> None: ...
+    @overload
     def body_encode(self, string: str) -> str: ...
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, __value: object) -> bool: ...

stdlib/email/utils.pyi

@@ -60,7 +60,7 @@ else:
     def localtime(dt: datetime.datetime | None = None, isdst: int = -1) -> datetime.datetime: ...
 
 def make_msgid(idstring: str | None = None, domain: str | None = None) -> str: ...
-def decode_rfc2231(s: str) -> tuple[str | None, str | None, str]: ...
+def decode_rfc2231(s: str) -> tuple[str | None, str | None, str]: ...  # May return list[str]. See issue #10431 for details.
 def encode_rfc2231(s: str, charset: str | None = None, language: str | None = None) -> str: ...
 def collapse_rfc2231_value(value: _ParamType, errors: str = "replace", fallback_charset: str = "us-ascii") -> str: ...
 def decode_params(params: list[tuple[str, str]]) -> list[tuple[str, _ParamType]]: ...