From 8228faa87dd243f6b3ab44140395ed3d0e6394cd Mon Sep 17 00:00:00 2001
From: danieleades <33452915+danieleades@users.noreply.github.com>
Date: Thu, 3 Oct 2024 04:31:35 +0100
Subject: [PATCH] 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         |  4 +++-
 stubs/docutils/docutils/frontend.pyi         |  5 ++---
 stubs/docutils/docutils/readers/doctree.pyi  |  2 +-
 stubs/docutils/docutils/writers/__init__.pyi | 23 ++++++++++++++++++--
 4 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/stubs/docutils/docutils/__init__.pyi b/stubs/docutils/docutils/__init__.pyi
index 006592eb5..f1f699cdf 100644
--- a/stubs/docutils/docutils/__init__.pyi
+++ b/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]]
 
diff --git a/stubs/docutils/docutils/frontend.pyi b/stubs/docutils/docutils/frontend.pyi
index 1aa500894..903130273 100644
--- a/stubs/docutils/docutils/frontend.pyi
+++ b/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,
diff --git a/stubs/docutils/docutils/readers/doctree.pyi b/stubs/docutils/docutils/readers/doctree.pyi
index 0001e5794..49c796cc7 100644
--- a/stubs/docutils/docutils/readers/doctree.pyi
+++ b/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]): ...
diff --git a/stubs/docutils/docutils/writers/__init__.pyi b/stubs/docutils/docutils/writers/__init__.pyi
index 0f6820f05..9f7ba543d 100644
--- a/stubs/docutils/docutils/writers/__init__.pyi
+++ b/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]]: ...