Improve docutils.parsers (#14191)

Author: donbarbos

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -11,7 +11,6 @@ docutils.nodes.NodeVisitor.visit_\w+  # Methods are discovered dynamically on co
 docutils.nodes.Text.__new__
 docutils.parsers.recommonmark_wrapper
 docutils.parsers.rst.directives.admonitions.BaseAdmonition.node_class  # must be overridden by base classes (pseudo-abstract)
-docutils.parsers.rst.directives.misc.MetaBody.__getattr__
 docutils.statemachine.State.nested_sm  # is initialised in __init__
 docutils.statemachine.State.nested_sm_kwargs  # is initialised in __init__
 docutils.statemachine.ViewList.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__

stubs/docutils/docutils/__init__.pyi

@@ -26,7 +26,7 @@ class ApplicationError(Exception): ...
 class DataError(ApplicationError): ...
 
 class SettingsSpec:
-    settings_spec: ClassVar[tuple[Any, ...]]
+    settings_spec: ClassVar[tuple[Any, ...]]  # Mixed tuple structure; uses Any for flexibility in nested option definitions
     settings_defaults: ClassVar[dict[Any, Any] | None]
     settings_default_overrides: ClassVar[dict[Any, Any] | None]
     relative_path_settings: ClassVar[tuple[Any, ...]]

stubs/docutils/docutils/parsers/__init__.pyi

@@ -1,15 +1,17 @@
-from typing import Any, ClassVar
+from typing import ClassVar, Final
 
 from docutils import Component
-from docutils.nodes import document as _document
+from docutils.nodes import _Document
+
+__docformat__: Final = "reStructuredText"
 
 class Parser(Component):
     component_type: ClassVar[str]
     config_section: ClassVar[str]
-    inputstring: Any  # defined after call to setup_parse()
-    document: Any  # defined after call to setup_parse()
-    def parse(self, inputstring: str, document: _document) -> None: ...
-    def setup_parse(self, inputstring: str, document: _document) -> None: ...
+    inputstring: str  # defined after call to setup_parse()
+    document: _Document  # defined after call to setup_parse()
+    def parse(self, inputstring: str, document: _Document) -> None: ...
+    def setup_parse(self, inputstring: str, document: _Document) -> None: ...
     def finish_parse(self) -> None: ...
 
 _parser_aliases: dict[str, str]

stubs/docutils/docutils/parsers/null.pyi

@@ -3,4 +3,5 @@ from typing import ClassVar
 from docutils import parsers
 
 class Parser(parsers.Parser):
+    supported: ClassVar[tuple[str, ...]]
     config_section_dependencies: ClassVar[tuple[str, ...]]

stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi

@@ -1 +1,50 @@
-def __getattr__(name: str): ...  # incomplete module
+from types import ModuleType
+from typing import ClassVar
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+class pending_xref(nodes.Inline, nodes.Element): ...
+
+sphinx: ModuleType
+
+def is_literal(node: nodes.Node) -> bool: ...
+
+class _CommonMarkParser:
+    default_config: ClassVar[dict[str, None]]
+    def __init__(self) -> None: ...
+    def convert_ast(self, ast): ...
+    def default_visit(self, mdnode): ...
+    def default_depart(self, mdnode): ...
+    def visit_heading(self, mdnode): ...
+    def depart_heading(self, _): ...
+    def visit_text(self, mdnode): ...
+    def visit_softbreak(self, _): ...
+    def visit_linebreak(self, _): ...
+    def visit_paragraph(self, mdnode): ...
+    def visit_emph(self, _): ...
+    def visit_strong(self, _): ...
+    def visit_code(self, mdnode): ...
+    def visit_link(self, mdnode): ...
+    def depart_link(self, mdnode): ...
+    def visit_image(self, mdnode): ...
+    def visit_list(self, mdnode): ...
+    def visit_item(self, mdnode): ...
+    def visit_code_block(self, mdnode): ...
+    def visit_block_quote(self, mdnode): ...
+    def visit_html(self, mdnode): ...
+    def visit_html_inline(self, mdnode): ...
+    def visit_html_block(self, mdnode): ...
+    def visit_thematic_break(self, _): ...
+    def setup_sections(self): ...
+    def add_section(self, section, level): ...
+    def is_section_level(self, level, section): ...
+
+class Parser(_CommonMarkParser):
+    supported: ClassVar[tuple[str, ...]]
+    config_section: ClassVar[str]
+    config_section_dependencies: ClassVar[tuple[str, ...]]
+    def get_transforms(self) -> list[type[Transform]]: ...
+    def parse(self, inputstring: str, document: nodes.document) -> None: ...
+    def visit_document(self, node) -> None: ...
+    def visit_text(self, mdnode) -> None: ...

stubs/docutils/docutils/parsers/rst/__init__.pyi

@@ -1,19 +1,22 @@
 from _typeshed import Incomplete
 from collections.abc import Callable, Sequence
-from typing import Any, ClassVar, Literal
+from typing import Any, ClassVar, Final, Literal
 from typing_extensions import TypeAlias
 
 from docutils import nodes, parsers
 from docutils.parsers.rst.states import Inliner, RSTState, RSTStateMachine
 from docutils.statemachine import StringList
 from docutils.transforms import Transform
+from docutils.utils import Reporter
+
+__docformat__: Final = "reStructuredText"
 
 class Parser(parsers.Parser):
-    settings_spec: ClassVar[Incomplete]
     config_section_dependencies: ClassVar[tuple[str, ...]]
     initial_state: Literal["Body", "RFC2822Body"]
     state_classes: Sequence[type[RSTState]]
     inliner: Inliner | None
+    statemachine: RSTStateMachine
     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: ...
@@ -27,22 +30,23 @@ class Directive:
     required_arguments: ClassVar[int]
     optional_arguments: ClassVar[int]
     final_argument_whitespace: ClassVar[bool]
-    option_spec: ClassVar[dict[str, Callable[[str], Any]] | None]
+    option_spec: ClassVar[dict[str, Callable[[str], Incomplete]] | None]
     has_content: ClassVar[bool]
     name: str
     arguments: list[str]
-    options: dict[str, Any]
+    options: dict[str, Incomplete]
     content: StringList
     lineno: int
     content_offset: int
     block_text: str
     state: RSTState
     state_machine: RSTStateMachine = ...
+    reporter: Reporter
     def __init__(
         self,
         name: str,
         arguments: list[str],
-        options: dict[str, Any],
+        options: dict[str, Incomplete],
         content: StringList,
         lineno: int,
         content_offset: int,

stubs/docutils/docutils/parsers/rst/directives/__init__.pyi

@@ -1,12 +1,14 @@
 from collections.abc import Callable, Container, Iterable, Sequence
 from re import Pattern
-from typing import Literal
+from typing import Final, Literal
 
 from docutils.languages import _LanguageModule
 from docutils.nodes import document, system_message
 from docutils.parsers import Parser
 from docutils.parsers.rst import Directive
 
+__docformat__: Final = "reStructuredText"
+
 def register_directive(name: str, directive: type[Directive]) -> None: ...
 def directive(
     directive_name: str, language_module: _LanguageModule, document: document
@@ -19,14 +21,14 @@ def uri(argument: str) -> str: ...
 def nonnegative_int(argument: str) -> int: ...
 def percentage(argument: str) -> int: ...
 
-length_units: list[str]
+length_units: Final[list[str]]
 
 def get_measure(argument: str, units: Iterable[str]) -> str: ...
 def length_or_unitless(argument: str) -> str: ...
 def length_or_percentage_or_unitless(argument: str, default: str = "") -> str: ...
 def class_option(argument: str) -> list[str]: ...
 
-unicode_pattern: Pattern[str]
+unicode_pattern: Final[Pattern[str]]
 
 def unicode_code(code: str) -> str: ...
 def single_char_or_unicode(argument: str) -> str: ...

stubs/docutils/docutils/parsers/rst/directives/admonitions.pyi

@@ -1,16 +1,39 @@
+from typing import Final
+
 from docutils import nodes
 from docutils.parsers.rst import Directive
 
+__docformat__: Final = "reStructuredText"
+
 class BaseAdmonition(Directive):
     node_class: type[nodes.Admonition]  # Subclasses must set this to the appropriate admonition node class.
 
-class Admonition(BaseAdmonition): ...
-class Attention(BaseAdmonition): ...
-class Caution(BaseAdmonition): ...
-class Danger(BaseAdmonition): ...
-class Error(BaseAdmonition): ...
-class Hint(BaseAdmonition): ...
-class Important(BaseAdmonition): ...
-class Note(BaseAdmonition): ...
-class Tip(BaseAdmonition): ...
-class Warning(BaseAdmonition): ...
+class Admonition(BaseAdmonition):
+    node_class: type[nodes.admonition]
+
+class Attention(BaseAdmonition):
+    node_class: type[nodes.attention]
+
+class Caution(BaseAdmonition):
+    node_class: type[nodes.caution]
+
+class Danger(BaseAdmonition):
+    node_class: type[nodes.danger]
+
+class Error(BaseAdmonition):
+    node_class: type[nodes.error]
+
+class Hint(BaseAdmonition):
+    node_class: type[nodes.hint]
+
+class Important(BaseAdmonition):
+    node_class: type[nodes.important]
+
+class Note(BaseAdmonition):
+    node_class: type[nodes.note]
+
+class Tip(BaseAdmonition):
+    node_class: type[nodes.tip]
+
+class Warning(BaseAdmonition):
+    node_class: type[nodes.warning]

stubs/docutils/docutils/parsers/rst/directives/body.pyi

@@ -1 +1,64 @@
-def __getattr__(name: str): ...  # incomplete module
+from collections.abc import Callable
+from typing import ClassVar, Final
+from typing_extensions import TypeAlias
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+__docformat__: Final = "reStructuredText"
+
+_DirectiveFn: TypeAlias = Callable[[str], str | list[str]]
+
+class BasePseudoSection(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    node_class: ClassVar[type[nodes.Node] | None]
+    def run(self): ...
+
+class Topic(BasePseudoSection):
+    node_class: ClassVar[type[nodes.Node]]
+
+class Sidebar(BasePseudoSection):
+    node_class: ClassVar[type[nodes.Node]]
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class LineBlock(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class ParsedLiteral(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class CodeBlock(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class MathBlock(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class Rubric(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class BlockQuote(Directive):
+    classes: ClassVar[list[str]]
+    def run(self): ...
+
+class Epigraph(BlockQuote):
+    classes: ClassVar[list[str]]
+
+class Highlights(BlockQuote):
+    classes: ClassVar[list[str]]
+
+class PullQuote(BlockQuote):
+    classes: ClassVar[list[str]]
+
+class Compound(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...
+
+class Container(Directive):
+    option_spec: ClassVar[dict[str, _DirectiveFn]]
+    def run(self): ...

stubs/docutils/docutils/parsers/rst/directives/html.pyi

@@ -1 +1,5 @@
-def __getattr__(name: str): ...  # incomplete module
+from typing import Final
+
+from docutils.parsers.rst.directives.misc import Meta as Meta, MetaBody as MetaBody
+
+__docformat__: Final = "reStructuredText"