[docutils] Add missing stubs (#14438)

Author: donBarbos

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -4,12 +4,15 @@ docutils.nodes.NodeVisitor.depart_\w+  # Methods are discovered dynamically on c
 docutils.nodes.NodeVisitor.visit_\w+  # Methods are discovered dynamically on commonly-used subclasses
 # 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.commonmark_wrapper # doesn't exist at runtime of stubtests
-docutils.parsers.recommonmark_wrapper # doesn't exist at runtime of stubtests
 docutils.parsers.rst.directives.admonitions.BaseAdmonition.node_class  # must be overridden by base classes (pseudo-abstract)
 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__
+docutils.transforms.Transform.apply # method apply is not implemented
 docutils.transforms.Transform.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
-docutils.writers.odf_odt.pygmentsformatter # this file is missing at runtime
+
+# Files that don't exist at runtime of stubtests, raises ImportError:
+docutils.parsers.commonmark_wrapper
+docutils.parsers.recommonmark_wrapper
+docutils.writers.odf_odt.pygmentsformatter # import `pygments` third-party library

stubs/docutils/METADATA.toml

@@ -1,6 +1,2 @@
 version = "0.21.*"
 upstream_repository = "https://sourceforge.net/p/docutils/code"
-partial_stub = true
-
-[tool.stubtest]
-ignore_missing_stub = true

stubs/docutils/docutils/__main__.pyi

@@ -0,0 +1,9 @@
+from typing import ClassVar
+
+import docutils
+
+class CliSettingsSpec(docutils.SettingsSpec):
+    config_section: ClassVar[str]
+    config_section_dependencies: ClassVar[tuple[str, ...]]
+
+def main() -> None: ...

stubs/docutils/docutils/languages/eo.pyi

@@ -1,6 +1,6 @@
-from _typeshed import Incomplete
+from typing import Final, Literal
 
-__docformat__: str
-labels: Incomplete
-bibliographic_fields: Incomplete
-author_separators: Incomplete
+__docformat__: Final = "reStructuredText"
+labels: dict[str, str]
+bibliographic_fields: dict[str, str]
+author_separators: list[Literal[";", ","]]

stubs/docutils/docutils/nodes.pyi

@@ -3,7 +3,7 @@ import xml.dom.minidom
 from abc import abstractmethod
 from collections import Counter
 from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence
-from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload
+from typing import Any, ClassVar, Final, Literal, Protocol, SupportsIndex, TypeVar, overload
 from typing_extensions import Self, TypeAlias
 
 from docutils.frontend import Values
@@ -15,6 +15,8 @@ _N = TypeVar("_N", bound=Node)
 class _DomModule(Protocol):
     Document: type[xml.dom.minidom.Document]
 
+__docformat__: Final = "reStructuredText"
+
 # Functional Node Base Classes
 
 class Node:

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

@@ -1,3 +1,4 @@
+from _typeshed import StrPath
 from pathlib import Path
 from re import Match, Pattern
 from typing import ClassVar, Final
@@ -7,6 +8,8 @@ from docutils.parsers.rst.states import SpecializedBody
 
 __docformat__: Final = "reStructuredText"
 
+def adapt_path(path: str, source: StrPath = "", root_prefix: StrPath = "/") -> str: ...
+
 class Include(Directive):
     standard_include_path: Path
 

stubs/docutils/docutils/parsers/rst/states.pyi

@@ -186,6 +186,8 @@ class Body(RSTState):
     pats: Incomplete
     patterns: ClassVar[dict[str, str | Pattern[str]]]
     initial_transitions: ClassVar[tuple[str, ...]]
+    sequence: str
+    format: str
     def indent(self, match, context, next_state): ...
     def block_quote(self, indented, line_offset): ...
     attribution_pattern: Incomplete

stubs/docutils/docutils/utils/math/math2html.pyi

@@ -51,6 +51,8 @@ class FormulaConfig:
     symbolfunctions: ClassVar[dict[str, str]]
     textfunctions: ClassVar[dict[str, str]]
     unmodified: ClassVar[dict[str, list[str]]]
+    key: str
+    value: str
 
 class CommandLineParser:
     options: Incomplete

stubs/docutils/docutils/writers/latex2e/__init__.pyi

@@ -1,6 +1,7 @@
 import re
 from _typeshed import Incomplete, StrPath, Unused
 from collections.abc import Callable, Iterable
+from io import TextIOWrapper
 from pathlib import Path
 from typing import ClassVar, Final, Literal, NoReturn, TypeVar
 from typing_extensions import deprecated
@@ -14,6 +15,8 @@ from docutils.writers import Writer as _Writer
 _K = TypeVar("_K")
 _V = TypeVar("_V")
 
+__docformat__: Final = "reStructuredText"
+
 LATEX_WRITER_DIR: Final[Path]
 
 class Writer(_Writer[str]):
@@ -62,6 +65,33 @@ class PreambleCmds:
     title_legacy: ClassVar[str]
     toc_list: ClassVar[str]
     ttem: ClassVar[str]
+    duclass: ClassVar[str]
+    providelength: ClassVar[str]
+    abstract: ClassVar[str]
+    dedication: ClassVar[str]
+    docinfo: ClassVar[str]
+    error: ClassVar[str]
+    highlight_rules: ClassVar[str]
+    admonition: ClassVar[str]
+    fieldlist: ClassVar[str]
+    footnotes: ClassVar[str]
+    inline: ClassVar[str]
+    legend: ClassVar[str]
+    lineblock: ClassVar[str]
+    optionlist: ClassVar[str]
+    rubric: ClassVar[str]
+    sidebar: ClassVar[str]
+    title: ClassVar[str]
+    subtitle: ClassVar[str]
+    documentsubtitle: ClassVar[str]
+    titlereference: ClassVar[str]
+    transition: ClassVar[str]
+    secnumdepth: ClassVar[str]
+
+fp: TextIOWrapper
+line: str
+block_name: str
+definitions: str
 
 class CharMaps:
     alltt: ClassVar[dict[int, str]]
@@ -181,6 +211,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def encode(self, text: str) -> str: ...
     def attval(self, text: str, whitespace: re.Pattern[str] = ...) -> str: ...
     def is_inline(self, node: nodes.Node) -> bool: ...
+    def ids_to_labels(
+        self, node: nodes.Element, set_anchor: bool = True, protect: bool = False, newline: bool = False
+    ) -> list[Incomplete]: ...
     def append_hypertargets(self, node: nodes.Element) -> None: ...
     def set_align_from_classes(self, node) -> None: ...
     def insert_align_declaration(self, node: nodes.Element, default: str | None = None) -> None: ...

stubs/docutils/docutils/writers/odf_odt/__init__.pyi

@@ -9,6 +9,7 @@ from xml.etree import ElementTree
 from docutils import nodes, writers
 from docutils.frontend import Values
 from docutils.languages import _LanguageModule
+from docutils.readers import standalone
 
 __docformat__: Final = "reStructuredText"
 VERSION: Final[str]
@@ -420,6 +421,4 @@ class ODFTranslator(nodes.GenericNodeVisitor):
     def visit_sidebar(self, node: nodes.sidebar) -> None: ...
     def depart_sidebar(self, node: nodes.sidebar) -> None: ...
 
-# TODO: readers is incomplete
-# from docutils.readers import standalone
-# class Reader(standalone.Reader): ...
+class Reader(standalone.Reader[str | bytes]): ...