[docutils] Impove main stubs (#14107)

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -1,8 +1,3 @@
-docutils.frontend.ConfigParser.__getattr__
-docutils.frontend.ConfigParser.read
-docutils.frontend.OptionParser.__getattr__
-docutils.io.FileOutput.__getattr__
-docutils.io.FileOutput.__init__
 docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__
 docutils.nodes.Element.tagname  # class variable is overridden in __init__ method
 docutils.nodes.NodeVisitor.depart_\w+  # Methods are discovered dynamically on commonly-used subclasses

stubs/docutils/docutils/__init__.pyi

@@ -1,10 +1,10 @@
-from typing import Any, ClassVar, NamedTuple
+from typing import Any, ClassVar, Final, NamedTuple
 from typing_extensions import Self
 
 from docutils.transforms import Transform
 
-__docformat__: str
-__version__: str
+__docformat__: Final = "reStructuredText"
+__version__: Final[str]
 
 class _VersionInfo(NamedTuple):
     major: int
@@ -19,8 +19,8 @@ class VersionInfo(_VersionInfo):
         cls, major: int = 0, minor: int = 0, micro: int = 0, releaselevel: str = "final", serial: int = 0, release: bool = True
     ) -> Self: ...
 
-__version_info__: VersionInfo
-__version_details__: str
+__version_info__: Final[VersionInfo]
+__version_details__: Final[str]
 
 class ApplicationError(Exception): ...
 class DataError(ApplicationError): ...

stubs/docutils/docutils/core.pyi

@@ -1,35 +1,50 @@
 from _typeshed import Incomplete
+from typing import Final
+from typing_extensions import deprecated
 
 from docutils import SettingsSpec
-from docutils.writers import _WriterParts
+from docutils.frontend import OptionParser
+from docutils.io import FileInput, Input, Output, StringInput
+from docutils.parsers import Parser
+from docutils.readers import Reader
+from docutils.utils import SystemMessage
+from docutils.writers import Writer, _WriterParts
 
-__docformat__: str
+__docformat__: Final = "reStructuredText"
 
 class Publisher:
-    document: Incomplete
-    reader: Incomplete
-    parser: Incomplete
-    writer: Incomplete
-    source: Incomplete
+    document: Incomplete | None
+    reader: Reader[Incomplete]
+    parser: Parser
+    writer: Writer[Incomplete]
+    source: Input[Incomplete]
     source_class: Incomplete
-    destination: Incomplete
+    destination: Output | None
     destination_class: Incomplete
-    settings: Incomplete
+    settings: dict[str, Incomplete]
     def __init__(
         self,
-        reader=None,
-        parser=None,
-        writer=None,
-        source=None,
+        reader: Reader[Incomplete] | None = None,
+        parser: Parser | None = None,
+        writer: Writer[Incomplete] | None = None,
+        source: Input[Incomplete] | None = None,
         source_class=...,
-        destination=None,
+        destination: Output | None = None,
         destination_class=...,
-        settings=None,
+        settings: dict[str, Incomplete] | None = None,
     ) -> None: ...
-    def set_reader(self, reader_name, parser, parser_name) -> None: ...
-    def set_writer(self, writer_name) -> None: ...
-    def set_components(self, reader_name, parser_name, writer_name) -> None: ...
-    def setup_option_parser(self, usage=None, description=None, settings_spec=None, config_section=None, **defaults): ...
+    def set_reader(self, reader_name: str, parser: Parser | None, parser_name: str | None) -> None: ...
+    def set_writer(self, writer_name: str) -> None: ...
+    def set_components(self, reader_name: str, parser_name: str, writer_name: str) -> None: ...
+    @deprecated("Publisher.setup_option_parser is deprecated, and will be removed in Docutils 0.21.")
+    def setup_option_parser(
+        self,
+        usage: str | None = None,
+        description: str | None = None,
+        settings_spec: SettingsSpec | None = None,
+        config_section: str | None = None,
+        **defaults,
+    ) -> OptionParser: ...
     def get_settings(
         self,
         usage: str | None = None,
@@ -40,7 +55,13 @@ class Publisher:
     ): ...
     def process_programmatic_settings(self, settings_spec, settings_overrides, config_section) -> None: ...
     def process_command_line(
-        self, argv=None, usage=None, description=None, settings_spec=None, config_section=None, **defaults
+        self,
+        argv: list[str] | None = None,
+        usage=None,
+        description: str | None = None,
+        settings_spec=None,
+        config_section=None,
+        **defaults,
     ) -> None: ...
     def set_io(self, source_path=None, destination_path=None) -> None: ...
     def set_source(self, source=None, source_path=None) -> None: ...
@@ -48,44 +69,44 @@ class Publisher:
     def apply_transforms(self) -> None: ...
     def publish(
         self,
-        argv=None,
-        usage=None,
-        description=None,
+        argv: list[str] | None = None,
+        usage: str | None = None,
+        description: str | None = None,
         settings_spec=None,
         settings_overrides=None,
-        config_section=None,
+        config_section: str | None = None,
         enable_exit_status: bool = False,
     ): ...
     def debugging_dumps(self) -> None: ...
     def prompt(self) -> None: ...
-    def report_Exception(self, error) -> None: ...
-    def report_SystemMessage(self, error) -> None: ...
-    def report_UnicodeError(self, error) -> None: ...
+    def report_Exception(self, error: BaseException) -> None: ...
+    def report_SystemMessage(self, error: SystemMessage) -> None: ...
+    def report_UnicodeError(self, error: UnicodeEncodeError) -> None: ...
 
-default_usage: str
-default_description: str
+default_usage: Final[str]
+default_description: Final[str]
 
 def publish_cmdline(
-    reader=None,
+    reader: Reader[Incomplete] | None = None,
     reader_name: str = "standalone",
-    parser=None,
+    parser: Parser | None = None,
     parser_name: str = "restructuredtext",
-    writer=None,
+    writer: Writer[Incomplete] | None = None,
     writer_name: str = "pseudoxml",
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = True,
-    argv=None,
-    usage=...,
-    description=...,
+    argv: list[str] | None = None,
+    usage: str = ...,
+    description: str = ...,
 ): ...
 def publish_file(
     source=None,
-    source_path=None,
+    source_path: FileInput | StringInput | None = None,
     destination=None,
-    destination_path=None,
+    destination_path: FileInput | StringInput | None = None,
     reader=None,
     reader_name: str = "standalone",
     parser=None,
@@ -95,13 +116,13 @@ def publish_file(
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
 def publish_string(
     source,
-    source_path=None,
-    destination_path=None,
+    source_path: FileInput | StringInput | None = None,
+    destination_path: FileInput | StringInput | None = None,
     reader=None,
     reader_name: str = "standalone",
     parser=None,
@@ -111,14 +132,14 @@ def publish_string(
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
 def publish_parts(
     source,
-    source_path=None,
+    source_path: FileInput | StringInput | None = None,
     source_class=...,
-    destination_path=None,
+    destination_path: FileInput | StringInput | None = None,
     reader=None,
     reader_name: str = "standalone",
     parser=None,
@@ -127,13 +148,13 @@ def publish_parts(
     writer_name: str = "pseudoxml",
     settings=None,
     settings_spec=None,
-    settings_overrides=None,
-    config_section=None,
+    settings_overrides: dict[str, Incomplete] | None = None,
+    config_section: str | None = None,
     enable_exit_status: bool = False,
 ) -> _WriterParts: ...
 def publish_doctree(
     source,
-    source_path=None,
+    source_path: FileInput | StringInput | None = None,
     source_class=...,
     reader=None,
     reader_name: str = "standalone",
@@ -142,18 +163,18 @@ def publish_doctree(
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
 def publish_from_doctree(
     document,
-    destination_path=None,
+    destination_path: FileInput | StringInput | None = None,
     writer=None,
     writer_name: str = "pseudoxml",
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
 def publish_cmdline_to_binary(
@@ -166,34 +187,34 @@ def publish_cmdline_to_binary(
     settings=None,
     settings_spec=None,
     settings_overrides=None,
-    config_section=None,
+    config_section: str | None = None,
     enable_exit_status: bool = True,
-    argv=None,
-    usage=...,
-    description=...,
+    argv: list[str] | None = None,
+    usage: str = ...,
+    description: str = ...,
     destination=None,
     destination_class=...,
 ): ...
 def publish_programmatically(
-    source_class,
+    source_class: type[FileInput],
     source,
-    source_path,
+    source_path: FileInput | StringInput,
     destination_class,
     destination,
-    destination_path,
+    destination_path: FileInput | StringInput,
     reader,
-    reader_name,
+    reader_name: str,
     parser,
-    parser_name,
+    parser_name: str,
     writer,
-    writer_name,
+    writer_name: str,
     settings,
     settings_spec,
     settings_overrides,
-    config_section,
-    enable_exit_status,
-): ...
-def rst2something(writer, documenttype, doc_path: str = "") -> None: ...
+    config_section: str,
+    enable_exit_status: bool,
+) -> tuple[str | bytes | None, Publisher]: ...
+def rst2something(writer: str, documenttype: str, doc_path: str = "") -> None: ...
 def rst2html() -> None: ...
 def rst2html4() -> None: ...
 def rst2html5() -> None: ...

stubs/docutils/docutils/examples.pyi

@@ -1 +1,46 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Incomplete
+from typing import Literal, overload
+from typing_extensions import TypeAlias
+
+from docutils.core import Publisher
+from docutils.io import FileInput, StringInput
+from docutils.nodes import document
+from docutils.writers import _WriterParts
+
+_HTMLHeaderLevel: TypeAlias = Literal[1, 2, 3, 4, 5, 6]
+
+def html_parts(
+    input_string: str,
+    source_path=None,
+    destination_path=None,
+    input_encoding: str = "unicode",
+    doctitle: bool = True,
+    initial_header_level: _HTMLHeaderLevel = 1,
+) -> _WriterParts: ...
+@overload
+def html_body(
+    input_string: str,
+    source_path=None,
+    destination_path=None,
+    input_encoding: str = "unicode",
+    output_encoding: Literal["unicode"] = "unicode",
+    doctitle: bool = True,
+    initial_header_level: _HTMLHeaderLevel = 1,
+) -> str: ...
+@overload
+def html_body(
+    input_string: str,
+    source_path=None,
+    destination_path=None,
+    input_encoding: str = "unicode",
+    output_encoding: str = "unicode",
+    doctitle: bool = True,
+    initial_header_level: _HTMLHeaderLevel = 1,
+) -> str | bytes: ...
+def internals(
+    input_string,
+    source_path: FileInput | StringInput | None = None,
+    destination_path: FileInput | StringInput | None = None,
+    input_encoding: str = "unicode",
+    settings_overrides: dict[str, Incomplete] | None = None,
+) -> tuple[document | None, Publisher]: ...

stubs/docutils/docutils/frontend.pyi

@@ -2,12 +2,12 @@ import optparse
 from _typeshed import Incomplete
 from collections.abc import Iterable, Mapping
 from configparser import RawConfigParser
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Final
 
 from docutils import SettingsSpec
 from docutils.utils import DependencyList
 
-__docformat__: str
+__docformat__: Final = "reStructuredText"
 
 def store_multiple(option, opt, value, parser, *args, **kwargs) -> None: ...
 def read_config_file(option, opt, value, parser) -> None: ...
@@ -15,6 +15,7 @@ def validate_encoding(setting, value=None, option_parser=None, config_parser=Non
 def validate_encoding_error_handler(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
 def validate_encoding_and_error_handler(setting, value, option_parser, config_parser=None, config_section=None): ...
 def validate_boolean(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> bool: ...
+def validate_ternary(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
 def validate_nonnegative_int(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> int: ...
 def validate_threshold(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> int: ...
 def validate_colon_separated_string_list(
@@ -23,6 +24,7 @@ def validate_colon_separated_string_list(
 def validate_comma_separated_list(
     setting, value=None, option_parser=None, config_parser=None, config_section=None
 ) -> list[str]: ...
+def validate_math_output(setting, value=None, option_parser=None, config_parser=None, config_section=None): ...
 def validate_url_trailing_slash(setting, value=None, option_parser=None, config_parser=None, config_section=None) -> str: ...
 def validate_dependency_file(
     setting, value=None, option_parser=None, config_parser=None, config_section=None
@@ -36,10 +38,16 @@ def make_one_path_absolute(base_path, path) -> str: ...
 def filter_settings_spec(settings_spec, *exclude, **replace) -> tuple[Any, ...]: ...
 
 class Values(optparse.Values):
+    record_dependencies: Incomplete
+    def __init__(self, *args, **kwargs) -> None: ...
     def update(self, other_dict, option_parser) -> None: ...
     def copy(self) -> Values: ...
+    def setdefault(self, name, default): ...
 
-class Option(optparse.Option): ...
+class Option(optparse.Option):
+    ATTRS: Incomplete
+    def __init__(self, *args, **kwargs) -> None: ...
+    def process(self, opt, value, values, parser): ...
 
 class OptionParser(optparse.OptionParser, SettingsSpec):
     standard_config_files: ClassVar[list[str]]
@@ -50,6 +58,11 @@ class OptionParser(optparse.OptionParser, SettingsSpec):
     default_error_encoding_error_handler: ClassVar[str]
     config_section: ClassVar[str]
     version_template: ClassVar[str]
+    lists: Incomplete
+    config_files: Incomplete
+    relative_path_settings: ClassVar[tuple[str, ...]]
+    version: Incomplete
+    components: Incomplete
     def __init__(
         self,
         components: Iterable[SettingsSpec | type[SettingsSpec]] = (),
@@ -58,11 +71,27 @@ class OptionParser(optparse.OptionParser, SettingsSpec):
         *args,
         **kwargs,
     ) -> None: ...
-    def __getattr__(self, name: str) -> Incomplete: ...
+    def populate_from_components(self, components) -> None: ...
+    @classmethod
+    def get_standard_config_files(cls): ...
+    def get_standard_config_settings(self): ...
+    def get_config_file_settings(self, config_file): ...
+    def check_values(self, values, args): ...
+    def check_args(self, args): ...
+    def set_defaults_from_dict(self, defaults) -> None: ...
+    def get_default_values(self): ...
+    def get_option_by_dest(self, dest): ...
 
 class ConfigParser(RawConfigParser):
-    def __getattr__(self, name: str) -> Incomplete: ...
+    old_settings: Incomplete
+    old_warning: str
+    not_utf8_error: str
+    def read(self, filenames, option_parser=None): ...
+    def handle_old_config(self, filename) -> None: ...
+    def validate_settings(self, filename, option_parser) -> None: ...
+    def optionxform(self, optionstr): ...
+    def get_section(self, section): ...
 
-class ConfigDeprecationWarning(DeprecationWarning): ...
+class ConfigDeprecationWarning(FutureWarning): ...
 
 def get_default_settings(*components) -> Values: ...

stubs/docutils/docutils/io.pyi

@@ -8,11 +8,11 @@ from _typeshed import (
     Unused,
 )
 from re import Pattern
-from typing import IO, Any, ClassVar, Generic, Literal, TypeVar
+from typing import IO, Any, ClassVar, Final, Generic, Literal, TypeVar
 
 from docutils import TransformSpec, nodes
 
-__docformat__: str
+__docformat__: Final = "reStructuredText"
 
 class InputError(OSError): ...
 class OutputError(OSError): ...
@@ -43,6 +43,10 @@ class Input(TransformSpec, Generic[_S]):
 class Output(TransformSpec):
     component_type: ClassVar[str]
     default_destination_path: ClassVar[str | None]
+    encoding: Incomplete
+    error_handler: Incomplete
+    destination: Incomplete
+    destination_path: Incomplete
     def __init__(
         self, destination=None, destination_path=None, encoding: str | None = None, error_handler: str = "strict"
     ) -> None: ...
@@ -50,6 +54,10 @@ class Output(TransformSpec):
     def encode(self, data: str) -> Any: ...  # returns bytes or str
 
 class ErrorOutput:
+    destination: Incomplete
+    encoding: Incomplete
+    encoding_errors: Incomplete
+    decoding_errors: Incomplete
     def __init__(
         self,
         destination: str | SupportsWrite[str] | SupportsWrite[bytes] | Literal[False] | None = None,
@@ -62,6 +70,9 @@ class ErrorOutput:
     def isatty(self) -> bool: ...
 
 class FileInput(Input[IO[str]]):
+    autoclose: Incomplete
+    source: Incomplete
+    source_path: Incomplete
     def __init__(
         self,
         source=None,
@@ -76,17 +87,36 @@ class FileInput(Input[IO[str]]):
     def close(self) -> None: ...
 
 class FileOutput(Output):
+    default_destination_path: ClassVar[str]
     mode: ClassVar[OpenTextModeWriting | OpenBinaryModeWriting]
-    def __getattr__(self, name: str) -> Incomplete: ...
+    opened: bool
+    autoclose: Incomplete
+    destination: Incomplete
+    destination_path: Incomplete
+    def __init__(
+        self,
+        destination=None,
+        destination_path=None,
+        encoding=None,
+        error_handler: str = "strict",
+        autoclose: bool = True,
+        handle_io_errors=None,
+        mode=None,
+    ) -> None: ...
+    def open(self) -> None: ...
+    def write(self, data): ...
+    def close(self) -> None: ...
 
 class BinaryFileOutput(FileOutput): ...
 
 class StringInput(Input[str]):
     default_source_path: ClassVar[str]
+    def read(self): ...
 
 class StringOutput(Output):
     default_destination_path: ClassVar[str]
     destination: str | bytes  # only defined after call to write()
+    def write(self, data): ...
 
 class NullInput(Input[Any]):
     default_source_path: ClassVar[str]
@@ -98,3 +128,4 @@ class NullOutput(Output):
 
 class DocTreeInput(Input[nodes.document]):
     default_source_path: ClassVar[str]
+    def read(self): ...

stubs/docutils/docutils/nodes.pyi

@@ -26,7 +26,10 @@ class Node:
     parent: Element | Any
     source: str | None
     line: int | None
-    document: document | None
+    @property
+    def document(self) -> document | None: ...
+    @document.setter
+    def document(self, value: document) -> None: ...
     def __bool__(self) -> Literal[True]: ...
     def asdom(self, dom: _DomModule | None = None) -> xml.dom.minidom.Element: ...
     # While docutils documents the Node class to be abstract it does not
@@ -414,6 +417,7 @@ class entry(Part, Element): ...
 
 class system_message(Special, BackLinkable, PreBibliographic, Element):
     def __init__(self, message: str | None = None, *children: Node, **attributes) -> None: ...
+    def astext(self) -> str: ...
 
 class pending(Special, Invisible, Element):
     transform: type[Transform]

stubs/docutils/docutils/statemachine.pyi

@@ -1,7 +1,7 @@
 import sys
 from collections.abc import Callable, Generator, Iterable, Iterator, Sequence
 from re import Match, Pattern
-from typing import Any, ClassVar, Generic, SupportsIndex, TypeVar, overload
+from typing import Any, ClassVar, Final, Generic, SupportsIndex, TypeVar, overload
 from typing_extensions import Self, TypeAlias
 
 _T = TypeVar("_T")
@@ -10,6 +10,8 @@ _TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]]
 _TransitionMethod: TypeAlias = Callable[[Match[str], _Context, str], _TransitionResult[_Context]]
 _Observer: TypeAlias = Callable[[StateMachine[_Context]], None]
 
+__docformat__: Final = "reStructuredText"
+
 class StateMachine(Generic[_Context]):
     input_lines: StringList | None
     input_offset: int
@@ -163,7 +165,7 @@ class ViewList(Generic[_T]):
     def source(self, i: int) -> str: ...
     def offset(self, i: int) -> int: ...
     def disconnect(self) -> None: ...
-    def xitems(self) -> Generator[tuple[str, int, str], None, None]: ...
+    def xitems(self) -> Generator[tuple[str, int, str]]: ...
     def pprint(self) -> None: ...
 
     # dummy atribute to indicate to mypy that ViewList is Iterable[str]