WIP: Impove docutils

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,49 @@
 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.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 = None, parser_name: str | None = 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,
@@ -49,11 +63,11 @@ class Publisher:
     def publish(
         self,
         argv=None,
-        usage=None,
-        description=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: ...
@@ -62,30 +76,30 @@ class Publisher:
     def report_SystemMessage(self, error) -> None: ...
     def report_UnicodeError(self, error) -> 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=...,
+    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 +109,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 +125,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 +141,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 +156,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 +180,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=...,
+    usage: str = ...,
+    description: str = ...,
     destination=None,
     destination_class=...,
 ): ...
 def publish_programmatically(
     source_class,
     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: ...
+) -> 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,42 @@
-def __getattr__(name: str): ...  # incomplete module
+from _typeshed import Incomplete
+from typing import Literal, overload
+
+from docutils.core import Publisher, _WriterParts
+from docutils.io import FileInput, StringInput
+from docutils.nodes import document
+
+def html_parts(
+    input_string: str,
+    source_path=None,
+    destination_path=None,
+    input_encoding: str = "unicode",
+    doctitle: bool = True,
+    initial_header_level: Literal[1, 2, 3, 4, 5, 6] = 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: Literal[1, 2, 3, 4, 5, 6] = 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: Literal[1, 2, 3, 4, 5, 6] = 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]: ...