Improve stubs for email.headerregistry (#6588)

* Add max_count class vars
* Add init() methods
* Fix ContentDispositionHeader.content_disposition return type

stdlib/email/headerregistry.pyi

@@ -1,5 +1,6 @@
 import sys
 import types
+from collections.abc import Iterable, Mapping
 from datetime import datetime as _datetime
 from email._header_value_parser import (
     AddressList,
@@ -12,28 +13,33 @@ from email._header_value_parser import (
 )
 from email.errors import MessageDefect
 from email.policy import Policy
-from typing import Any, Iterable, Tuple, Type
+from typing import Any, ClassVar, Tuple, Type
+from typing_extensions import Literal
 
 class BaseHeader(str):
+    # max_count is actually more of an abstract ClassVar (not defined on the base class, but expected to be defined in subclasses)
+    max_count: ClassVar[Literal[1] | None]
     @property
     def name(self) -> str: ...
     @property
     def defects(self) -> Tuple[MessageDefect, ...]: ...
-    @property
-    def max_count(self) -> int | None: ...
     def __new__(cls, name: str, value: Any) -> BaseHeader: ...
     def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect]) -> None: ...
     def fold(self, *, policy: Policy) -> str: ...
 
 class UnstructuredHeader:
+    max_count: ClassVar[Literal[1] | None]
     @staticmethod
     def value_parser(value: str) -> UnstructuredTokenList: ...
     @classmethod
     def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
 
-class UniqueUnstructuredHeader(UnstructuredHeader): ...
+class UniqueUnstructuredHeader(UnstructuredHeader):
+    max_count: ClassVar[Literal[1]]
 
 class DateHeader:
+    max_count: ClassVar[Literal[1] | None]
+    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect], datetime: _datetime) -> None: ...
     @property
     def datetime(self) -> _datetime: ...
     @staticmethod
@@ -41,9 +47,12 @@ class DateHeader:
     @classmethod
     def parse(cls, value: str | _datetime, kwds: dict[str, Any]) -> None: ...
 
-class UniqueDateHeader(DateHeader): ...
+class UniqueDateHeader(DateHeader):
+    max_count: ClassVar[Literal[1]]
 
 class AddressHeader:
+    max_count: ClassVar[Literal[1] | None]
+    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect], groups: Iterable[Group]) -> None: ...
     @property
     def groups(self) -> Tuple[Group, ...]: ...
     @property
@@ -53,15 +62,28 @@ class AddressHeader:
     @classmethod
     def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
 
-class UniqueAddressHeader(AddressHeader): ...
+class UniqueAddressHeader(AddressHeader):
+    max_count: ClassVar[Literal[1]]
 
 class SingleAddressHeader(AddressHeader):
     @property
     def address(self) -> Address: ...
 
-class UniqueSingleAddressHeader(SingleAddressHeader): ...
+class UniqueSingleAddressHeader(SingleAddressHeader):
+    max_count: ClassVar[Literal[1]]
 
 class MIMEVersionHeader:
+    max_count: ClassVar[Literal[1]]
+    def init(
+        self,
+        name: str,
+        *,
+        parse_tree: TokenList,
+        defects: Iterable[MessageDefect],
+        version: str | None,
+        major: int | None,
+        minor: int | None,
+    ) -> None: ...
     @property
     def version(self) -> str | None: ...
     @property
@@ -74,6 +96,8 @@ class MIMEVersionHeader:
     def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
 
 class ParameterizedMIMEHeader:
+    max_count: ClassVar[Literal[1]]
+    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect], params: Mapping[str, Any]) -> None: ...
     @property
     def params(self) -> types.MappingProxyType[str, Any]: ...
     @classmethod
@@ -90,12 +114,15 @@ class ContentTypeHeader(ParameterizedMIMEHeader):
     def value_parser(value: str) -> ContentType: ...
 
 class ContentDispositionHeader(ParameterizedMIMEHeader):
+    # init is redefined but has the same signature as parent class, so is omitted from the stub
     @property
-    def content_disposition(self) -> str: ...
+    def content_disposition(self) -> str | None: ...
     @staticmethod
     def value_parser(value: str) -> ContentDisposition: ...
 
 class ContentTransferEncodingHeader:
+    max_count: ClassVar[Literal[1]]
+    def init(self, name: str, *, parse_tree: TokenList, defects: Iterable[MessageDefect]) -> None: ...
     @property
     def cte(self) -> str: ...
     @classmethod
@@ -106,6 +133,7 @@ class ContentTransferEncodingHeader:
 if sys.version_info >= (3, 8):
     from email._header_value_parser import MessageID
     class MessageIDHeader:
+        max_count: ClassVar[Literal[1]]
         @classmethod
         def parse(cls, value: str, kwds: dict[str, Any]) -> None: ...
         @staticmethod