[docutils] Add missing stubs for transforms dir (#14234)

Author: donBarbos

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -11,6 +11,5 @@ docutils.statemachine.State.nested_sm  # is initialised in __init__
 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.transforms.Transformer.__getattr__
 docutils.TransformSpec.unknown_reference_resolvers
 docutils.writers.manpage.Translator.__getattr__

stubs/docutils/docutils/transforms/__init__.pyi

@@ -1,14 +1,36 @@
 from _typeshed import Incomplete
+from collections.abc import Iterable, Mapping
+from typing import Any, ClassVar, Final
+from typing_extensions import TypeAlias
 
-from docutils.nodes import Node, document
+from docutils import ApplicationError, TransformSpec, nodes
+from docutils.languages import LanguageImporter
+
+_TransformTuple: TypeAlias = tuple[str, type[Transform], nodes.Node | None, dict[str, Any]]
+
+__docformat__: Final = "reStructuredText"
+
+class TransformError(ApplicationError): ...
 
 class Transform:
-    def __init__(self, document: document, startnode: Node | None = None): ...
-    def __getattr__(self, name: str, /) -> Incomplete: ...
+    default_priority: ClassVar[int | None]
+    document: nodes.document
+    startnode: nodes.Node | None
+    language: LanguageImporter
+    def __init__(self, document: nodes.document, startnode: nodes.Node | None = None) -> None: ...
+    def __getattr__(self, name: str, /) -> Incomplete: ...  # method apply is not implemented
 
-class Transformer:
-    def __init__(self, document: document): ...
+class Transformer(TransformSpec):
+    transforms: list[_TransformTuple]
+    document: nodes.document
+    applied: list[_TransformTuple]
+    sorted: bool
+    components: Mapping[str, TransformSpec]
+    serialno: int
+    def __init__(self, document: nodes.document): ...
     def add_transform(self, transform_class: type[Transform], priority: int | None = None, **kwargs) -> None: ...
-    def __getattr__(self, name: str, /) -> Incomplete: ...
-
-def __getattr__(name: str): ...  # incomplete module
+    def add_transforms(self, transform_list: Iterable[type[Transform]]) -> None: ...
+    def add_pending(self, pending: nodes.pending, priority: int | None = None) -> None: ...
+    def get_priority_string(self, priority: int) -> str: ...
+    def populate_from_components(self, components: Iterable[TransformSpec]) -> None: ...
+    def apply_transforms(self) -> None: ...

stubs/docutils/docutils/transforms/components.pyi

@@ -0,0 +1,9 @@
+from typing import ClassVar, Final
+
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class Filter(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...

stubs/docutils/docutils/transforms/frontmatter.pyi

@@ -0,0 +1,34 @@
+import re
+from typing import ClassVar, Final
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class TitlePromoter(Transform):
+    def promote_title(self, node: nodes.Element) -> bool: ...
+    def promote_subtitle(self, node: nodes.Element) -> bool: ...
+    def candidate_index(self, node: nodes.Element) -> tuple[nodes.Node, int] | tuple[None, None]: ...
+
+class DocTitle(TitlePromoter):
+    default_priority: ClassVar[int]
+    def set_metadata(self) -> None: ...
+    def apply(self) -> None: ...
+
+class SectionSubTitle(TitlePromoter):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class DocInfo(Transform):
+    default_priority: ClassVar[int]
+    biblio_nodes: ClassVar[dict[str, type[nodes.Element]]]
+    rcs_keyword_substitutions: ClassVar[list[tuple[re.Pattern[str], str]]]
+    def apply(self) -> None: ...
+    def extract_bibliographic(self, field_list): ...
+    def check_empty_biblio_field(self, field, name) -> bool: ...
+    def check_compound_biblio_field(self, field, name) -> bool: ...
+    def extract_authors(self, field, name, docinfo) -> None: ...
+    def authors_from_one_paragraph(self, field) -> list[list[nodes.Text]]: ...
+    def authors_from_bullet_list(self, field): ...
+    def authors_from_paragraphs(self, field): ...

stubs/docutils/docutils/transforms/misc.pyi

@@ -0,0 +1,19 @@
+from typing import ClassVar, Final
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class CallBack(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class ClassAttribute(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class Transitions(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+    def visit_transition(self, node: nodes.transition) -> None: ...

stubs/docutils/docutils/transforms/parts.pyi

@@ -0,0 +1,34 @@
+from _typeshed import Incomplete, Unused
+from collections.abc import Iterable, Sequence
+from typing import ClassVar, Final, NoReturn
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class SectNum(Transform):
+    default_priority: ClassVar[int]
+    maxdepth: int
+    startvalue: int
+    prefix: str
+    suffix: str
+    def apply(self) -> None: ...
+    def update_section_numbers(self, node: nodes.Element, prefix: Iterable[str] = (), depth: int = 0) -> None: ...
+
+class Contents(Transform):
+    default_priority: ClassVar[int]
+    toc_id: Incomplete
+    backlinks: Incomplete
+    def apply(self) -> None: ...
+    def build_contents(
+        self, node: nodes.Element, level: int = 0
+    ) -> nodes.bullet_list | list[None]: ...  # return empty list if entries is empty
+    def copy_and_filter(self, node: nodes.Node) -> Sequence[nodes.Node]: ...
+
+class ContentsFilter(nodes.TreeCopyVisitor):
+    def get_entry_text(self) -> Sequence[nodes.Node]: ...
+    def ignore_node_but_process_children(self, node: Unused) -> NoReturn: ...
+    visit_problematic = ignore_node_but_process_children
+    visit_reference = ignore_node_but_process_children
+    visit_target = ignore_node_but_process_children

stubs/docutils/docutils/transforms/peps.pyi

@@ -0,0 +1,43 @@
+import re
+from typing import ClassVar, Final
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class Headers(Transform):
+    default_priority: ClassVar[int]
+    pep_url: ClassVar[str]
+    pep_cvs_url: ClassVar[str]
+    rcs_keyword_substitutions: ClassVar[tuple[tuple[re.Pattern[str], str], ...]]
+    def apply(self) -> None: ...
+
+class Contents(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class TargetNotes(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+    def cleanup_callback(self, pending: nodes.pending) -> None: ...
+
+class PEPZero(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class PEPZeroSpecial(nodes.SparseNodeVisitor):
+    pep_url: ClassVar[str]
+    def unknown_visit(self, node: nodes.Node) -> None: ...
+    def visit_reference(self, node: nodes.reference) -> None: ...
+    def visit_field_list(self, node: nodes.field_list) -> None: ...
+    pep_table: bool
+    entry: int
+    def visit_tgroup(self, node: nodes.tgroup) -> None: ...
+    def visit_colspec(self, node: nodes.colspec) -> None: ...
+    def visit_row(self, node: nodes.row) -> None: ...
+    def visit_entry(self, node: nodes.entry) -> None: ...
+
+non_masked_addresses: tuple[str, ...]
+
+def mask_email(ref: nodes.reference, pepno: int | None = None) -> nodes.Node: ...

stubs/docutils/docutils/transforms/references.pyi

@@ -0,0 +1,75 @@
+from _typeshed import Incomplete
+from collections.abc import Iterable
+from typing import ClassVar, Final, overload
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class PropagateTargets(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class AnonymousHyperlinks(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class IndirectHyperlinks(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+    def resolve_indirect_target(self, target: nodes.Element) -> None: ...
+    def nonexistent_indirect_target(self, target: nodes.Element) -> None: ...
+    def circular_indirect_reference(self, target: nodes.Element) -> None: ...
+    def indirect_target_error(self, target: nodes.Element, explanation) -> None: ...
+    def resolve_indirect_references(self, target: nodes.Element) -> None: ...
+
+class ExternalTargets(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class InternalTargets(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+    def resolve_reference_ids(self, target: nodes.Element) -> None: ...
+
+class Footnotes(Transform):
+    default_priority: ClassVar[int]
+    autofootnote_labels: list[str] | None
+    symbols: ClassVar[list[str]]
+    def apply(self) -> None: ...
+    def number_footnotes(self, startnum: int) -> int: ...
+    def number_footnote_references(self, startnum: int) -> None: ...
+    def symbolize_footnotes(self) -> None: ...
+    def resolve_footnotes_and_citations(self) -> None: ...
+    @overload
+    def resolve_references(self, note: nodes.footnote, reflist: Iterable[nodes.footnote_reference]) -> None: ...
+    @overload
+    def resolve_references(self, note: nodes.citation, reflist: Iterable[nodes.citation_reference]) -> None: ...
+    @overload
+    def resolve_references(self, note: nodes.title, reflist: Iterable[nodes.title_reference]) -> None: ...
+
+class CircularSubstitutionDefinitionError(Exception): ...
+
+class Substitutions(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class TargetNotes(Transform):
+    default_priority: ClassVar[int]
+    classes: Incomplete
+    def __init__(self, document: nodes.document, startnode: nodes.Node) -> None: ...
+    def apply(self) -> None: ...
+    def make_target_footnote(self, refuri: str, refs: list[Incomplete], notes: dict[Incomplete, Incomplete]): ...
+
+class DanglingReferences(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class DanglingReferencesVisitor(nodes.SparseNodeVisitor):
+    document: nodes.document
+    def __init__(self, document: nodes.document, unknown_reference_resolvers) -> None: ...
+    def unknown_visit(self, node: nodes.Node) -> None: ...
+    def visit_reference(self, node: nodes.reference) -> None: ...
+    def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: ...
+    def visit_citation_reference(self, node: nodes.citation_reference) -> None: ...

stubs/docutils/docutils/transforms/universal.pyi

@@ -0,0 +1,52 @@
+from _typeshed import Incomplete
+from collections.abc import Generator, Iterable
+from typing import ClassVar, Final, Literal
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+class Decorations(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+    def generate_header(self) -> None: ...
+    def generate_footer(self) -> list[nodes.paragraph] | None: ...
+
+class ExposeInternals(Transform):
+    default_priority: ClassVar[int]
+    def not_Text(self, node: object) -> bool: ...  # node passing to isinstance() method
+    def apply(self) -> None: ...
+
+class Messages(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class FilterMessages(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class TestMessages(Transform):
+    __test__: bool
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class StripComments(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...
+
+class StripClassesAndElements(Transform):
+    default_priority: ClassVar[int]
+    strip_elements: set[Incomplete]
+    def apply(self) -> None: ...
+    def check_classes(self, node: object) -> bool: ...
+
+class SmartQuotes(Transform):
+    default_priority: ClassVar[int]
+    nodes_to_skip: ClassVar[tuple[type[nodes.Node], ...]]
+    literal_nodes: ClassVar[tuple[type[nodes.Node | nodes.Body], ...]]
+    smartquotes_action: ClassVar[str]
+    unsupported_languages: set[str]
+    def __init__(self, document: nodes.document, startnode: nodes.Node | None) -> None: ...
+    def get_tokens(self, txtnodes: Iterable[nodes.Node]) -> Generator[tuple[Literal["literal", "plain"], str]]: ...
+    def apply(self) -> None: ...

stubs/docutils/docutils/transforms/writer_aux.pyi

@@ -0,0 +1,17 @@
+from typing import ClassVar, Final
+from typing_extensions import deprecated
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+__docformat__: Final = "reStructuredText"
+
+@deprecated("docutils.transforms.writer_aux.Compound is deprecated and will be removed in Docutils 0.21 or later.")
+class Compound(Transform):
+    default_priority: ClassVar[int]
+    def __init__(self, document: nodes.document, startnode: nodes.Node | None = None) -> None: ...
+    def apply(self) -> None: ...
+
+class Admonitions(Transform):
+    default_priority: ClassVar[int]
+    def apply(self) -> None: ...