From 3646f644b846d393d9381daf38141835a8217b21 Mon Sep 17 00:00:00 2001
From: danieleades <33452915+danieleades@users.noreply.github.com>
Date: Fri, 8 Mar 2024 14:14:00 +0000
Subject: [PATCH] Improve type annotations in 'docutils.parsers.rst' (#11523)

---
 stubs/docutils/@tests/stubtest_allowlist.txt  |  2 -
 .../docutils/parsers/rst/__init__.pyi         | 59 +++++++++++++++----
 2 files changed, 46 insertions(+), 15 deletions(-)

diff --git a/stubs/docutils/@tests/stubtest_allowlist.txt b/stubs/docutils/@tests/stubtest_allowlist.txt
index d81d13ec4..0178c2f64 100644
--- a/stubs/docutils/@tests/stubtest_allowlist.txt
+++ b/stubs/docutils/@tests/stubtest_allowlist.txt
@@ -11,11 +11,9 @@ docutils.nodes.GenericNodeVisitor.__getattr__
 # these methods take a rawsource parameter that has been deprecated and is completely ignored, so we omit it from the stub
 docutils.nodes.Text.__new__
 docutils.parsers.recommonmark_wrapper
-docutils.parsers.rst.Directive.__getattr__
 docutils.transforms.Transform.__getattr__
 docutils.transforms.Transformer.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
 docutils.utils.Reporter.__getattr__
-
 # the constructor appears to be mostly internal API, public API users are meant to use docutils.utils.new_reporter instead
 docutils.utils.Reporter.__init__
diff --git a/stubs/docutils/docutils/parsers/rst/__init__.pyi b/stubs/docutils/docutils/parsers/rst/__init__.pyi
index 46f7ee5b3..3eb4ef963 100644
--- a/stubs/docutils/docutils/parsers/rst/__init__.pyi
+++ b/stubs/docutils/docutils/parsers/rst/__init__.pyi
@@ -1,34 +1,67 @@
 from _typeshed import Incomplete
+from collections.abc import Callable, Sequence
 from typing import Any, ClassVar, Literal
+from typing_extensions import TypeAlias
 
-from docutils import parsers
-from docutils.parsers.rst import states
+from docutils import nodes, parsers
+from docutils.parsers.rst.states import Inliner, RSTState, RSTStateMachine
+from docutils.statemachine import StringList
+from docutils.transforms import Transform
 
 class Parser(parsers.Parser):
+    settings_spec: ClassVar[Incomplete]
     config_section_dependencies: ClassVar[tuple[str, ...]]
     initial_state: Literal["Body", "RFC2822Body"]
-    state_classes: Any
-    inliner: Any
-    def __init__(self, rfc2822: bool = False, inliner: Incomplete | None = None) -> None: ...
+    state_classes: Sequence[type[RSTState]]
+    inliner: Inliner | None
+    def __init__(self, rfc2822: bool = False, inliner: Inliner | None = None) -> None: ...
+    def get_transforms(self) -> list[type[Transform]]: ...
+    def parse(self, inputstring: str, document: nodes.document) -> None: ...
 
 class DirectiveError(Exception):
-    level: Any
+    level: int
     msg: str
-    def __init__(self, level: Any, message: str) -> None: ...
+    def __init__(self, level: int, message: str) -> None: ...
 
 class Directive:
+    required_arguments: int
+    optional_arguments: int
+    final_argument_whitespace: bool
+    option_spec: dict[str, Callable[[str], Any]] | None
+    has_content: bool
+    name: str
+    arguments: list[str]
+    options: dict[str, Any]
+    content: StringList
+    lineno: int
+    content_offset: int
+    block_text: str
+    state: RSTState
+    state_machine: RSTStateMachine = ...
     def __init__(
         self,
         name: str,
-        arguments: list[Any],
+        arguments: list[str],
         options: dict[str, Any],
-        content: list[str],
+        content: StringList,
         lineno: int,
         content_offset: int,
         block_text: str,
-        state: states.RSTState,
-        state_machine: states.RSTStateMachine,
+        state: RSTState,
+        state_machine: RSTStateMachine,
     ) -> None: ...
-    def __getattr__(self, name: str) -> Incomplete: ...
+    def run(self) -> Sequence[nodes.Node]: ...
+    def directive_error(self, level: int, message: str) -> DirectiveError: ...
+    def debug(self, message: str) -> DirectiveError: ...
+    def info(self, message: str) -> DirectiveError: ...
+    def warning(self, message: str) -> DirectiveError: ...
+    def error(self, message: str) -> DirectiveError: ...
+    def severe(self, message: str) -> DirectiveError: ...
+    def assert_has_content(self) -> None: ...
+    def add_name(self, node: nodes.Node) -> None: ...
 
-def convert_directive_function(directive_fn): ...
+_DirectiveFn: TypeAlias = Callable[
+    [str, list[str], dict[str, Any], StringList, int, int, str, RSTState, RSTStateMachine], Directive
+]
+
+def convert_directive_function(directive_fn: _DirectiveFn) -> type[Directive]: ...