improve type annotations in 'docutils.io.Input' (#11540)

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -3,7 +3,6 @@ docutils.frontend.ConfigParser.read
 docutils.frontend.OptionParser.__getattr__
 docutils.io.FileOutput.__getattr__
 docutils.io.FileOutput.__init__
-docutils.io.Input.__init__
 docutils.languages.LanguageImporter.__getattr__
 docutils.nodes.Element.__getattr__
 docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__

stubs/docutils/docutils/io.pyi

@@ -8,9 +8,9 @@ from _typeshed import (
     Unused,
 )
 from re import Pattern
-from typing import Any, ClassVar, Literal
+from typing import IO, Any, ClassVar, Generic, Literal, TypeVar
 
-from docutils import TransformSpec
+from docutils import TransformSpec, nodes
 
 __docformat__: str
 
@@ -20,10 +20,20 @@ class OutputError(OSError): ...
 def check_encoding(stream: Any, encoding: str) -> bool | None: ...
 def error_string(err: BaseException) -> str: ...
 
-class Input(TransformSpec):
+_S = TypeVar("_S")
+
+class Input(TransformSpec, Generic[_S]):
     component_type: ClassVar[str]
     default_source_path: ClassVar[str | None]
-    def read(self) -> Any: ...
+    encoding: str | None
+    error_handler: str
+    source: _S | None
+    source_path: str | None
+    successful_encoding: str | None = None
+    def __init__(
+        self, source: _S | None = None, source_path: str | None = None, encoding: str | None = None, error_handler: str = "strict"
+    ) -> None: ...
+    def read(self) -> str: ...
     def decode(self, data: str | bytes | bytearray) -> str: ...
     coding_slug: ClassVar[Pattern[bytes]]
     byte_order_marks: ClassVar[tuple[tuple[bytes, str], ...]]
@@ -55,7 +65,7 @@ class ErrorOutput:
     def close(self) -> None: ...
     def isatty(self) -> bool: ...
 
-class FileInput(Input):
+class FileInput(Input[IO[str]]):
     def __init__(
         self,
         source: Incomplete | None = None,
@@ -75,14 +85,14 @@ class FileOutput(Output):
 
 class BinaryFileOutput(FileOutput): ...
 
-class StringInput(Input):
+class StringInput(Input[str]):
     default_source_path: ClassVar[str]
 
 class StringOutput(Output):
     default_destination_path: ClassVar[str]
     destination: str | bytes  # only defined after call to write()
 
-class NullInput(Input):
+class NullInput(Input[Any]):
     default_source_path: ClassVar[str]
     def read(self) -> str: ...
 
@@ -90,5 +100,5 @@ class NullOutput(Output):
     default_destination_path: ClassVar[str]
     def write(self, data: Unused) -> None: ...
 
-class DocTreeInput(Input):
+class DocTreeInput(Input[nodes.document]):
     default_source_path: ClassVar[str]

stubs/docutils/docutils/readers/__init__.pyi

@@ -1,4 +1,4 @@
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Generic, TypeVar
 
 from docutils import Component, nodes
 from docutils.frontend import Values
@@ -6,21 +6,23 @@ from docutils.io import Input
 from docutils.parsers import Parser
 from docutils.transforms import Transform
 
-class Reader(Component):
+_S = TypeVar("_S")
+
+class Reader(Component, Generic[_S]):
     component_type: ClassVar[str]
     config_section: ClassVar[str]
     def get_transforms(self) -> list[type[Transform]]: ...
     def __init__(self, parser: Parser | None = None, parser_name: str | None = None) -> None: ...
     parser: Parser | None
-    source: Input | None
+    source: Input[_S] | None
     input: str | Any | None
     def set_parser(self, parser_name: str) -> None: ...
-    def read(self, source: Input, parser: Parser, settings: Values) -> nodes.document: ...
+    def read(self, source: Input[_S], parser: Parser, settings: Values) -> nodes.document: ...
     document: nodes.document
     def parse(self) -> None: ...
     def new_document(self) -> nodes.document: ...
 
-class ReReader(Reader):
+class ReReader(Reader[_S]):
     def get_transforms(self) -> list[type[Transform]]: ...
 
-def get_reader_class(reader_name: str) -> type[Reader]: ...
+def get_reader_class(reader_name: str) -> type[Reader[Any]]: ...

stubs/docutils/docutils/readers/doctree.pyi

@@ -1,3 +1,7 @@
+from typing import TypeVar
+
 from docutils import readers
 
-class Reader(readers.ReReader): ...
+_S = TypeVar("_S")
+
+class Reader(readers.ReReader[_S]): ...