From ea34c97ccca90b5eb18bdaa40a1ac053f0098f67 Mon Sep 17 00:00:00 2001
From: Adam Dangoor <adamdangoor@gmail.com>
Date: Wed, 3 Jul 2024 13:23:56 +0100
Subject: [PATCH] Expand docutils.parsters.rst.states (#12226)

---
 .../docutils/parsers/rst/__init__.pyi         |  8 +--
 .../docutils/docutils/parsers/rst/states.pyi  | 51 ++++++++++++++++++-
 2 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/stubs/docutils/docutils/parsers/rst/__init__.pyi b/stubs/docutils/docutils/parsers/rst/__init__.pyi
index 2d5d619ff..6b151cd62 100644
--- a/stubs/docutils/docutils/parsers/rst/__init__.pyi
+++ b/stubs/docutils/docutils/parsers/rst/__init__.pyi
@@ -12,7 +12,7 @@ class Parser(parsers.Parser):
     settings_spec: ClassVar[Incomplete]
     config_section_dependencies: ClassVar[tuple[str, ...]]
     initial_state: Literal["Body", "RFC2822Body"]
-    state_classes: Sequence[type[RSTState]]
+    state_classes: Sequence[type[RSTState[Incomplete]]]
     inliner: Inliner | None
     def __init__(self, rfc2822: bool = False, inliner: Inliner | None = None) -> None: ...
     def get_transforms(self) -> list[type[Transform]]: ...
@@ -36,7 +36,7 @@ class Directive:
     lineno: int
     content_offset: int
     block_text: str
-    state: RSTState
+    state: RSTState[Incomplete]
     state_machine: RSTStateMachine = ...
     def __init__(
         self,
@@ -47,7 +47,7 @@ class Directive:
         lineno: int,
         content_offset: int,
         block_text: str,
-        state: RSTState,
+        state: RSTState[Incomplete],
         state_machine: RSTStateMachine,
     ) -> None: ...
     def run(self) -> Sequence[nodes.Node]: ...
@@ -61,7 +61,7 @@ class Directive:
     def add_name(self, node: nodes.Node) -> None: ...
 
 _DirectiveFn: TypeAlias = Callable[
-    [str, list[str], dict[str, Any], StringList, int, int, str, RSTState, RSTStateMachine], Directive
+    [str, list[str], dict[str, Any], StringList, int, int, str, RSTState[Incomplete], RSTStateMachine], Directive
 ]
 
 def convert_directive_function(directive_fn: _DirectiveFn) -> type[Directive]: ...
diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi
index de8094214..af22fcf25 100644
--- a/stubs/docutils/docutils/parsers/rst/states.pyi
+++ b/stubs/docutils/docutils/parsers/rst/states.pyi
@@ -2,15 +2,64 @@ from _typeshed import Incomplete
 from collections.abc import Callable, Sequence
 from re import Match, Pattern
 from types import ModuleType
-from typing import Any
+from typing import Any, TypeVar
 from typing_extensions import TypeAlias
 
 from docutils import nodes
+from docutils.statemachine import StateMachineWS, StateWS
 from docutils.utils import Reporter
 
+_Context = TypeVar("_Context")
+
 class Struct:
     def __init__(self, **keywordargs) -> None: ...
 
+class RSTState(StateWS[_Context]):
+    nested_sm: type[StateMachineWS[_Context]]
+    nested_sm_cache: Incomplete
+    nested_sm_kwargs: Incomplete
+    def __init__(self, state_machine, debug: bool = False) -> None: ...
+    memo: Incomplete
+    reporter: Incomplete
+    inliner: Incomplete
+    document: nodes.document
+    parent: Incomplete
+    def runtime_init(self) -> None: ...
+    def goto_line(self, abs_line_offset) -> None: ...
+    def no_match(self, context, transitions): ...
+    def bof(self, context): ...
+    def nested_parse(
+        self,
+        block,
+        input_offset,
+        node,
+        match_titles: bool = False,
+        state_machine_class: Incomplete | None = None,
+        state_machine_kwargs: Incomplete | None = None,
+    ): ...
+    def nested_list_parse(
+        self,
+        block,
+        input_offset,
+        node,
+        initial_state,
+        blank_finish,
+        blank_finish_state: Incomplete | None = None,
+        extra_settings={},
+        match_titles: bool = False,
+        state_machine_class: Incomplete | None = None,
+        state_machine_kwargs: Incomplete | None = None,
+    ): ...
+    def section(self, title, source, style, lineno, messages) -> None: ...
+    def check_subsection(self, source, style, lineno): ...
+    def title_inconsistent(self, sourcetext, lineno): ...
+    def new_subsection(self, title, lineno, messages) -> None: ...
+    def paragraph(self, lines, lineno): ...
+    def inline_text(self, text, lineno): ...
+    def unindent_warning(self, node_name): ...
+
+def build_regexp(definition, compile: bool = True): ...
+
 _BasicDefinition: TypeAlias = tuple[str, str, str, list[Pattern[str]]]
 _DefinitionParts: TypeAlias = tuple[str, str, str, list[Pattern[str] | _BasicDefinition]]
 _DefinitionType: TypeAlias = tuple[str, str, str, list[Pattern[str] | _DefinitionParts]]