diff --git a/stubs/docutils/@tests/stubtest_allowlist.txt b/stubs/docutils/@tests/stubtest_allowlist.txt index 5b0f264c1591..662f1d33707a 100644 --- a/stubs/docutils/@tests/stubtest_allowlist.txt +++ b/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__ diff --git a/stubs/docutils/METADATA.toml b/stubs/docutils/METADATA.toml index 17d320a94b90..9550463d6ca4 100644 --- a/stubs/docutils/METADATA.toml +++ b/stubs/docutils/METADATA.toml @@ -1 +1 @@ -version = "0.17.*" +version = "0.18.*" diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 7df55c0bd92c..6efe7c5e2b63 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/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