[docutils] Add missing stubs for writers dir (#14223)

Author: donBarbos

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -12,4 +12,4 @@ 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.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
-docutils.writers.manpage.Translator.__getattr__
+docutils.writers.odf_odt.pygmentsformatter # this file is missing at runtime

stubs/docutils/docutils/writers/__init__.pyi

@@ -1,4 +1,4 @@
-from typing import Any, Generic, TypedDict, TypeVar, type_check_only
+from typing import Any, Final, Generic, TypedDict, TypeVar, type_check_only
 from typing_extensions import Required
 
 from docutils import Component, nodes
@@ -7,6 +7,8 @@ from docutils.languages import LanguageImporter
 
 _S = TypeVar("_S")
 
+__docformat__: Final = "reStructuredText"
+
 # It would probably be better to specialize writers for subclasses,
 # but this gives us all possible Writer items w/o instance checks
 @type_check_only
@@ -67,13 +69,13 @@ class _WriterParts(TypedDict, total=False):
 class Writer(Component, Generic[_S]):
     parts: _WriterParts
     language: LanguageImporter | None = None
-    def __init__(self) -> None: ...
     document: nodes.document | None = None
     destination: Output | None = None
     output: _S | None = None
-    def assemble_parts(self) -> None: ...
-    def translate(self) -> None: ...
+    def __init__(self) -> None: ...
     def write(self, document: nodes.document, destination: Output) -> str | bytes | None: ...
+    def translate(self) -> None: ...
+    def assemble_parts(self) -> None: ...
 
 class UnfilteredWriter(Writer[_S]): ...
 

stubs/docutils/docutils/writers/_html_base.pyi

@@ -1 +1,45 @@
-def __getattr__(name: str): ...  # incomplete module
+from collections.abc import Callable
+from typing import ClassVar, Final
+from xml.sax.handler import ContentHandler
+from xml.sax.xmlreader import Locator, XMLReader
+
+import docutils
+from docutils import nodes, writers
+from docutils.frontend import Values
+
+__docformat__: Final = "reStructuredText"
+
+class RawXmlError(docutils.ApplicationError): ...
+
+class Writer(writers.Writer[str]):
+    settings_defaults: ClassVar[dict[str, str]]
+    config_section: ClassVar[str]
+    config_section_dependencies: ClassVar[tuple[str, ...]]
+    translator_class: type[XMLTranslator]
+    visitor: XMLTranslator
+
+class XMLTranslator(nodes.GenericNodeVisitor):
+    doctype: ClassVar[str]
+    generator: ClassVar[str]
+    xmlparser: ClassVar[XMLReader]
+    warn: Callable[..., nodes.system_message]
+    error: Callable[..., nodes.system_message]
+    settings: Values
+    indent: str
+    newline: str
+    level: int
+    in_simple: int
+    fixed_text: int
+    output: list[str]
+    the_handle: TestXml
+    def __init__(self, document: nodes.document) -> None: ...
+    simple_nodes: ClassVar[tuple[type[nodes.Element], ...]]
+    def default_visit(self, node: nodes.Element) -> None: ...  # type: ignore[override]
+    def default_departure(self, node: nodes.Element) -> None: ...  # type: ignore[override]
+    def visit_Text(self, node: nodes.Text) -> None: ...
+    def depart_Text(self, node: nodes.Text) -> None: ...
+    def visit_raw(self, node: nodes.raw) -> None: ...
+
+class TestXml(ContentHandler):
+    locator: Locator
+    def setDocumentLocator(self, locator: Locator) -> None: ...

stubs/docutils/docutils/writers/docutils_xml.pyi

@@ -0,0 +1,125 @@
+from _typeshed import Incomplete
+from typing import ClassVar, Final
+
+from docutils import nodes
+from docutils.writers import _html_base
+
+__docformat__: Final = "reStructuredText"
+
+class Writer(_html_base.Writer):
+    default_stylesheets: ClassVar[list[str]]
+    default_stylesheet_dirs: ClassVar[list[str]]
+    default_template: ClassVar[str]
+    config_section: ClassVar[str]
+    translator_class: type[HTMLTranslator]
+
+class HTMLTranslator(_html_base.HTMLTranslator):
+    content_type: ClassVar[str]
+    content_type_mathml: ClassVar[str]
+    object_image_types: ClassVar[dict[str, str]]
+    def set_first_last(self, node) -> None: ...
+    def visit_address(self, node: nodes.address) -> None: ...
+    def depart_address(self, node: nodes.address) -> None: ...
+    def visit_admonition(self, node: nodes.admonition) -> None: ...
+    def depart_admonition(self, node: nodes.admonition | None = None) -> None: ...
+    def visit_author(self, node: nodes.author) -> None: ...
+    author_in_authors: bool
+    def depart_author(self, node: nodes.author) -> None: ...
+    def visit_authors(self, node: nodes.authors) -> None: ...
+    def depart_authors(self, node: nodes.authors) -> None: ...
+    def visit_colspec(self, node: nodes.colspec) -> None: ...
+    def depart_colspec(self, node: nodes.colspec) -> None: ...
+    def is_compactable(self, node: nodes.Element) -> bool: ...
+    def visit_citation(self, node: nodes.citation) -> None: ...
+    def depart_citation(self, node: nodes.citation) -> None: ...
+    def visit_citation_reference(self, node: nodes.citation_reference) -> None: ...
+    def depart_citation_reference(self, node: nodes.citation_reference) -> None: ...
+    def visit_classifier(self, node: nodes.classifier) -> None: ...
+    def depart_classifier(self, node: nodes.classifier) -> None: ...
+    def visit_compound(self, node: nodes.compound) -> None: ...
+    def depart_compound(self, node: nodes.compound) -> None: ...
+    def visit_definition(self, node: nodes.definition) -> None: ...
+    def depart_definition(self, node: nodes.definition) -> None: ...
+    def visit_definition_list(self, node: nodes.definition_list) -> None: ...
+    def depart_definition_list(self, node: nodes.definition_list) -> None: ...
+    def visit_definition_list_item(self, node: nodes.definition_list_item) -> None: ...
+    def depart_definition_list_item(self, node: nodes.definition_list_item) -> None: ...
+    def visit_description(self, node: nodes.description) -> None: ...
+    def depart_description(self, node: nodes.description) -> None: ...
+    in_docinfo: bool
+    def visit_docinfo(self, node: nodes.docinfo) -> None: ...
+    docinfo: Incomplete
+    body: Incomplete
+    def depart_docinfo(self, node: nodes.docinfo) -> None: ...
+    def visit_docinfo_item(self, node, name, meta: bool = True) -> None: ...
+    def depart_docinfo_item(self) -> None: ...
+    def visit_doctest_block(self, node) -> None: ...
+    def depart_doctest_block(self, node) -> None: ...
+    def visit_entry(self, node) -> None: ...
+    def depart_entry(self, node) -> None: ...
+    compact_p: Incomplete
+    compact_simple: Incomplete
+    def visit_enumerated_list(self, node) -> None: ...
+    def depart_enumerated_list(self, node) -> None: ...
+    def visit_field(self, node) -> None: ...
+    def depart_field(self, node) -> None: ...
+    def visit_field_body(self, node) -> None: ...
+    def depart_field_body(self, node) -> None: ...
+    compact_field_list: bool
+    def visit_field_list(self, node: nodes.field_list) -> None: ...
+    def depart_field_list(self, node: nodes.field_list) -> None: ...
+    def visit_field_name(self, node: nodes.field_name) -> None: ...
+    def depart_field_name(self, node: nodes.field_name) -> None: ...
+    def visit_footnote(self, node: nodes.footnote) -> None: ...
+    def footnote_backrefs(self, node: nodes.footnote) -> None: ...
+    def depart_footnote(self, node: nodes.footnote) -> None: ...
+    def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: ...
+    def depart_footnote_reference(self, node: nodes.footnote_reference) -> None: ...
+    def visit_generated(self, node: nodes.generated) -> None: ...
+    def visit_image(self, node: nodes.image) -> None: ...
+    def depart_image(self, node: nodes.image) -> None: ...
+    def visit_label(self, node: nodes.label) -> None: ...
+    def depart_label(self, node: nodes.label) -> None: ...
+    def visit_list_item(self, node: nodes.list_item) -> None: ...
+    def depart_list_item(self, node: nodes.list_item) -> None: ...
+    def visit_literal(self, node: nodes.literal) -> None: ...
+    def depart_literal(self, node: nodes.literal) -> None: ...
+    def visit_literal_block(self, node: nodes.literal_block) -> None: ...
+    def depart_literal_block(self, node: nodes.literal_block) -> None: ...
+    def visit_option_group(self, node: nodes.option_group) -> None: ...
+    def depart_option_group(self, node: nodes.option_group) -> None: ...
+    def visit_option_list(self, node: nodes.option_list) -> None: ...
+    def depart_option_list(self, node: nodes.option_list) -> None: ...
+    def visit_option_list_item(self, node: nodes.option_list_item) -> None: ...
+    def depart_option_list_item(self, node: nodes.option_list_item) -> None: ...
+    def should_be_compact_paragraph(self, node: nodes.Element) -> bool: ...
+    def visit_paragraph(self, node: nodes.paragraph) -> None: ...
+    def depart_paragraph(self, node: nodes.paragraph) -> None: ...
+    in_sidebar: bool
+    def visit_sidebar(self, node: nodes.sidebar) -> None: ...
+    def depart_sidebar(self, node: nodes.sidebar) -> None: ...
+    def visit_subscript(self, node: nodes.subscript) -> None: ...
+    def depart_subscript(self, node: nodes.subscript) -> None: ...
+    in_document_title: int
+    def visit_subtitle(self, node: nodes.subtitle) -> None: ...
+    subtitle: list[Incomplete]
+    def depart_subtitle(self, node: nodes.subtitle) -> None: ...
+    def visit_superscript(self, node: nodes.superscript) -> None: ...
+    def depart_superscript(self, node: nodes.superscript) -> None: ...
+    def visit_system_message(self, node: nodes.system_message) -> None: ...
+    def depart_system_message(self, node: nodes.system_message) -> None: ...
+    def visit_table(self, node: nodes.table) -> None: ...
+    def depart_table(self, node: nodes.table) -> None: ...
+    def visit_tbody(self, node: nodes.tbody) -> None: ...
+    def depart_tbody(self, node: nodes.tbody) -> None: ...
+    def visit_term(self, node: nodes.term) -> None: ...
+    def depart_term(self, node: nodes.term) -> None: ...
+    def visit_thead(self, node: nodes.thead) -> None: ...
+    def depart_thead(self, node: nodes.thead) -> None: ...
+    def section_title_tags(self, node: nodes.Element) -> tuple[str, str]: ...
+
+class SimpleListChecker(_html_base.SimpleListChecker):
+    def visit_list_item(self, node: nodes.list_item) -> None: ...
+    def visit_paragraph(self, node: nodes.paragraph) -> None: ...
+    def visit_definition_list(self, node: nodes.definition_list) -> None: ...
+    def visit_docinfo(self, node: nodes.docinfo) -> None: ...

stubs/docutils/docutils/writers/html4css1.pyi

@@ -0,0 +1,16 @@
+from pathlib import Path
+from typing import ClassVar, Final
+
+from docutils.writers import _html_base
+
+__docformat__: Final = "reStructuredText"
+
+class Writer(_html_base.Writer):
+    default_stylesheets: ClassVar[list[str]]
+    default_stylesheet_dirs: ClassVar[list[str]]
+    default_template: ClassVar[Path]
+    translator_class: type[HTMLTranslator]
+
+class HTMLTranslator(_html_base.HTMLTranslator):
+    supported_block_tags: set[str]
+    supported_inline_tags: set[str]