add type annotations to docutils.writers (#12420)

Co-authored-by: daniel.eades <daniel.eades@seebyte.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: James Addison <55152140+jayaddison@users.noreply.github.com>

stubs/docutils/docutils/__init__.pyi

@@ -1,6 +1,8 @@
 from typing import Any, ClassVar, NamedTuple
 from typing_extensions import Self
 
+from docutils.transforms import Transform
+
 __docformat__: str
 __version__: str
 
@@ -32,7 +34,7 @@ class SettingsSpec:
     config_section_dependencies: ClassVar[tuple[str, ...] | None]
 
 class TransformSpec:
-    def get_transforms(self) -> list[Any]: ...
+    def get_transforms(self) -> list[type[Transform]]: ...
     default_transforms: ClassVar[tuple[Any, ...]]
     unknown_reference_resolvers: ClassVar[list[Any]]
 

stubs/docutils/docutils/frontend.pyi

@@ -4,8 +4,7 @@ from collections.abc import Iterable, Mapping
 from configparser import RawConfigParser
 from typing import Any, ClassVar
 
-from docutils import SettingsSpec
-from docutils.parsers import Parser
+from docutils import Component, SettingsSpec
 from docutils.utils import DependencyList
 
 __docformat__: str
@@ -113,7 +112,7 @@ class OptionParser(optparse.OptionParser, SettingsSpec):
     version_template: ClassVar[str]
     def __init__(
         self,
-        components: Iterable[type[Parser]] = (),
+        components: Iterable[Component] = (),
         defaults: Mapping[str, Any] | None = None,
         read_config_files: bool | None = False,
         *args,

stubs/docutils/docutils/readers/doctree.pyi

@@ -2,6 +2,6 @@ from typing import TypeVar
 
 from docutils import readers
 
-_S = TypeVar("_S")
+_S = TypeVar("_S", bound=str | bytes)
 
 class Reader(readers.ReReader[_S]): ...

stubs/docutils/docutils/writers/__init__.pyi

@@ -1,3 +1,22 @@
-from _typeshed import Incomplete
+from typing import Any, Generic, TypeVar
 
-def __getattr__(name: str) -> Incomplete: ...
+from docutils import Component, nodes
+from docutils.io import Output
+from docutils.languages import LanguageImporter
+
+_S = TypeVar("_S")
+
+class Writer(Component, Generic[_S]):
+    parts: dict[str, Any]
+    language: LanguageImporter | None = None
+    def __init__(self) -> None: ...
+    document: nodes.document | None = None
+    destination: Output | None = None
+    output: _S | None = None
+    def assemble_parts(self) -> None: ...
+    def translate(self) -> None: ...
+    def write(self, document: nodes.document, destination: Output) -> str | bytes | None: ...
+
+class UnfilteredWriter(Writer[_S]): ...
+
+def get_writer_class(writer_name: str) -> type[Writer[Any]]: ...