[docutils] Impove main stubs (#14107)

Author: donBarbos

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,52 +55,58 @@ 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: ...
     def set_destination(self, destination=None, destination_path=None) -> None: ...
     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]: ...