[docutils] Bump to 0.22.*

Closes: python#14496

Author: donBarbos

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -1,7 +1,9 @@
 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
+docutils.nodes.NodeVisitor.depart_\w+ # Methods are discovered dynamically on commonly-used subclasses
 docutils.nodes.NodeVisitor.visit_\w+  # Methods are discovered dynamically on commonly-used subclasses
+docutils.nodes.NodeVisitor.__init__   # Argument "document" should be positional-only, but subclasses are not
+
 # 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.rst.directives.admonitions.BaseAdmonition.node_class  # must be overridden by base classes (pseudo-abstract)
@@ -11,8 +13,26 @@ docutils.statemachine.ViewList.__iter__ # doesn't exist at runtime, but the clas
 docutils.transforms.Transform.apply # method apply is not implemented
 docutils.transforms.Transform.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
+docutils.writers.latex2e.PreambleCmds... contents
 
 # 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
+
+# `TYPE_CHECKING` variable is for internal use:
+docutils.TYPE_CHECKING
+docutils.core.TYPE_CHECKING
+docutils.examples.TYPE_CHECKING
+docutils.frontend.TYPE_CHECKING
+docutils.io.TYPE_CHECKING
+docutils.languages.TYPE_CHECKING
+docutils.nodes.TYPE_CHECKING
+docutils.parsers.TYPE_CHECKING
+docutils.parsers.rst.directives.TYPE_CHECKING
+docutils.parsers.rst.directives.misc.TYPE_CHECKING
+docutils.parsers.rst.languages.TYPE_CHECKING
+docutils.readers.TYPE_CHECKING
+docutils.utils.TYPE_CHECKING
+docutils.writers.TYPE_CHECKING
+docutils.writers._html_base.TYPE_CHECKING

stubs/docutils/METADATA.toml

@@ -1,2 +1,2 @@
-version = "0.21.*"
+version = "0.22.*"
 upstream_repository = "https://sourceforge.net/p/docutils/code"

stubs/docutils/docutils/__main__.pyi

@@ -1,7 +1,9 @@
-from typing import ClassVar
+from typing import ClassVar, Final
 
 import docutils
 
+__docformat__: Final = "reStructuredText"
+
 class CliSettingsSpec(docutils.SettingsSpec):
     config_section: ClassVar[str]
     config_section_dependencies: ClassVar[tuple[str, ...]]

stubs/docutils/docutils/core.pyi

@@ -3,7 +3,6 @@ from typing import Final
 from typing_extensions import deprecated
 
 from docutils import SettingsSpec
-from docutils.frontend import OptionParser
 from docutils.io import FileInput, Input, Output
 from docutils.parsers import Parser
 from docutils.readers import Reader
@@ -33,18 +32,10 @@ class Publisher:
         destination_class=...,
         settings: dict[str, Incomplete] | None = None,
     ) -> None: ...
-    def set_reader(self, reader_name: str, parser: Parser | None, parser_name: str | None) -> None: ...
+    def set_reader(self, reader: str, parser: Parser | None = None, parser_name: str | None = None) -> None: ...
     def set_writer(self, writer_name: str) -> None: ...
+    @deprecated("The `Publisher.set_components()` will be removed in Docutils 2.0.")
     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,
@@ -64,7 +55,7 @@ class Publisher:
         **defaults,
     ) -> None: ...
     def set_io(self, source_path: StrPath | None = None, destination_path: StrPath | None = None) -> None: ...
-    def set_source(self, source=None, source_path: StrPath | None = None) -> None: ...
+    def set_source(self, source: str | None = None, source_path: StrPath | None = None) -> None: ...
     def set_destination(self, destination=None, destination_path: StrPath | None = None) -> None: ...
     def apply_transforms(self) -> None: ...
     def publish(
@@ -88,11 +79,11 @@ default_description: Final[str]
 
 def publish_cmdline(
     reader: Reader[Incomplete] | None = None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser: Parser | None = None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer: Writer[Incomplete] | None = None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -108,11 +99,11 @@ def publish_file(
     destination=None,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -124,11 +115,11 @@ def publish_string(
     source_path: StrPath | None = None,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -141,11 +132,11 @@ def publish_parts(
     source_class=...,
     destination_path: StrPath | None = None,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides: dict[str, Incomplete] | None = None,
@@ -157,9 +148,9 @@ def publish_doctree(
     source_path: StrPath | None = None,
     source_class=...,
     reader=None,
-    reader_name: str = "standalone",
+    reader_name: str | None = None,
     parser=None,
-    parser_name: str = "restructuredtext",
+    parser_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
@@ -170,13 +161,14 @@ def publish_from_doctree(
     document,
     destination_path: StrPath | None = None,
     writer=None,
-    writer_name: str = "pseudoxml",
+    writer_name: str | None = None,
     settings=None,
     settings_spec=None,
     settings_overrides=None,
     config_section: str | None = None,
     enable_exit_status: bool = False,
 ): ...
+@deprecated("The `publish_cmdline_to_binary()` is deprecated  by `publish_cmdline()` and will be removed in Docutils 0.24.")
 def publish_cmdline_to_binary(
     reader=None,
     reader_name: str = "standalone",

stubs/docutils/docutils/examples.pyi

@@ -1,46 +1,44 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, StrPath
 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_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = 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_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = 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_string: str | bytes,
+    source_path: StrPath | None = None,
+    destination_path: StrPath | None = 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,
+    source: str,
+    source_path: StrPath | None = None,
     input_encoding: str = "unicode",
     settings_overrides: dict[str, Incomplete] | None = None,
 ) -> tuple[document | None, Publisher]: ...