docutils: complete nodes.Node & bump version to 0.18.* (#7380)

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -8,7 +8,7 @@ docutils.io.Input.__getattr__
 docutils.io.Input.__init__
 docutils.languages.LanguageImporter.__getattr__
 docutils.nodes.Element.__getattr__
-docutils.nodes.Node.__getattr__
+docutils.nodes.NodeVisitor.__getattr__
 docutils.nodes.document.__getattr__
 docutils.nodes.document.__init__
 docutils.parsers.rst.Directive.__getattr__
@@ -18,3 +18,7 @@ docutils.utils.Reporter.__getattr__
 
 # the constructor appears to be mostly internal API, public API users are meant to use docutils.utils.new_reporter instead
 docutils.utils.Reporter.__init__
+
+# 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.nodes.Text.__init__

stubs/docutils/METADATA.toml

@@ -1 +1 @@
-version = "0.17.*"
+version = "0.18.*"

stubs/docutils/docutils/nodes.pyi

@@ -1,15 +1,81 @@
+import xml.dom.minidom
 from _typeshed import Self
-from collections.abc import Iterable
-from typing import Any, overload
+from abc import abstractmethod
+from collections.abc import Callable, Generator, Iterable, Sequence
+from typing import Any, ClassVar, Protocol, TypeVar, overload
+from typing_extensions import Literal
 
 from docutils.transforms import Transformer
 
+_N = TypeVar("_N", bound=Node)
+
+class _DomModule(Protocol):
+    Document: type[xml.dom.minidom.Document]
+
 class Node:
+    # children is initialized by the subclasses
+    children: Sequence[Node]
     parent: Node | None
     source: str | None
     line: int | None
     document: document | None
-    def __getattr__(self, __name: str) -> Any: ...  # incomplete
+    def __bool__(self) -> Literal[True]: ...
+    def asdom(self, dom: _DomModule | None = ...) -> xml.dom.minidom.Element: ...
+    # While docutils documents the Node class to be abstract it does not
+    # actually use the ABCMeta metaclass. We still set @abstractmethod here
+    # (although it's not used in the docutils implementation) because it
+    # makes Mypy reject Node() with "Cannot instantiate abstract class".
+    @abstractmethod
+    def copy(self: Self) -> Self: ...
+    @abstractmethod
+    def deepcopy(self: Self) -> Self: ...
+    @abstractmethod
+    def pformat(self, indent: str = ..., level: int = ...) -> str: ...
+    @abstractmethod
+    def astext(self) -> str: ...
+    def setup_child(self, child: Node) -> None: ...
+    def walk(self, visitor: NodeVisitor) -> bool: ...
+    def walkabout(self, visitor: NodeVisitor) -> bool: ...
+    @overload
+    def findall(
+        self, condition: type[_N], include_self: bool = ..., descend: bool = ..., siblings: bool = ..., ascend: bool = ...
+    ) -> Generator[_N, None, None]: ...
+    @overload
+    def findall(
+        self,
+        condition: Callable[[Node], bool] | None = ...,
+        include_self: bool = ...,
+        descend: bool = ...,
+        siblings: bool = ...,
+        ascend: bool = ...,
+    ) -> Generator[Node, None, None]: ...
+    @overload
+    def traverse(
+        self, condition: type[_N], include_self: bool = ..., descend: bool = ..., siblings: bool = ..., ascend: bool = ...
+    ) -> list[_N]: ...
+    @overload
+    def traverse(
+        self,
+        condition: Callable[[Node], bool] | None = ...,
+        include_self: bool = ...,
+        descend: bool = ...,
+        siblings: bool = ...,
+        ascend: bool = ...,
+    ) -> list[Node]: ...
+    @overload
+    def next_node(
+        self, condition: type[_N], include_self: bool = ..., descend: bool = ..., siblings: bool = ..., ascend: bool = ...
+    ) -> _N: ...
+    @overload
+    def next_node(
+        self,
+        condition: Callable[[Node], bool] | None = ...,
+        include_self: bool = ...,
+        descend: bool = ...,
+        siblings: bool = ...,
+        ascend: bool = ...,
+    ) -> Node: ...
+    def previous_sibling(self) -> Node | None: ...
 
 class Element(Node):
     children: list[Node]
@@ -32,13 +98,40 @@ class Element(Node):
     def __add__(self, other: list[Node]) -> list[Node]: ...
     def __radd__(self, other: list[Node]) -> list[Node]: ...
     def __iadd__(self: Self, other: Node | Iterable[Node]) -> Self: ...
+    def copy(self: Self) -> Self: ...
+    def deepcopy(self: Self) -> Self: ...
+    def pformat(self, indent: str = ..., level: int = ...) -> str: ...
+    def astext(self) -> str: ...
     def __getattr__(self, __name: str) -> Any: ...  # incomplete
 
+class Text(Node, str):
+    tagname: ClassVar[str]
+    children: tuple[()]
+
+    # we omit the rawsource parameter because it has been deprecated and is ignored
+    def __new__(cls: type[Self], data: str) -> Self: ...
+    def __init__(self, data: str) -> None: ...
+    def shortrepr(self, maxlen: int = ...) -> str: ...
+    def copy(self: Self) -> Self: ...
+    def deepcopy(self: Self) -> Self: ...
+    def pformat(self, indent: str = ..., level: int = ...) -> str: ...
+    def astext(self) -> str: ...
+    def rstrip(self, chars: str | None = ...) -> str: ...
+    def lstrip(self, chars: str | None = ...) -> str: ...
+
 class Structural: ...
 class Root: ...
 
 class document(Root, Structural, Element):
     transformer: Transformer
+    def copy(self: Self) -> Self: ...
+    def deepcopy(self: Self) -> Self: ...
+    def pformat(self, indent: str = ..., level: int = ...) -> str: ...
+    def astext(self) -> str: ...
+    def __getattr__(self, __name: str) -> Any: ...  # incomplete
+
+class NodeVisitor:
+    def __init__(self, document: document): ...
     def __getattr__(self, __name: str) -> Any: ...  # incomplete
 
 def __getattr__(name: str) -> Any: ...  # incomplete