docutils: complete nodes.Node & bump version to 0.18.*

[not-my-profile]

The version bump is necessary because
Node.findall() was introduced in 0.18.1.

[not-my-profile]

question I had because I misread the error message

Passing a type as the condition to Node.findall is equivalent to lambda n: isinstance(n, type) ... hence the overload:

@overload
def findall(self, condition: type[_N], ...) -> Generator[_N, None, None]: ...
@overload
def findall(self, condition: Callable[[Node], bool] = ..., ...) -> Generator[Node, None, None]: ...

I intentionally omitted the = ... for condition in the first overload because otherwise, Pyright picks the first overload for node.findall() and infers _N@findall as a return type, which is obviously wrong.

Omitting the default value for the first overload however results in mypy.stubtest failing:

error: docutils.nodes.Node.findall is inconsistent, runtime argument "condition" has a default value of type None, which is incompatible with stub argument type Union[Type[_N`-1], def (docutils.nodes.Node) -> builtins.bool]. This is often caused by overloads failing to account for explicitly passing in the default value.

What do you suggest?

Inferring _N@findall for the return type shouldn't lead to type checking errors since _N is bounded by Node but I'd still prefer type checkers to infer Node as a return type for node.findall() because _N@findall might confuse users looking at the type tooltips in their IDE.

Sidenote: I unfortunately cannot check if mypy infers the same because of python/mypy#12241.

[Akuli]

Didn't read most of the PR yet, but this should answer your question.

[Akuli]

Sidenote: I unfortunately cannot check if mypy infers the same because of python/mypy#12241.

You can set the MYPYPATH environment variable:

(env) akuli@akuli-desktop:~/typeshed$ cat asd.py
from docutils.nodes import Element
e: Element
reveal_type(e.findall())

(env) akuli@akuli-desktop:~/typeshed$ MYPYPATH=stubs/docutils/ mypy asd.py
asd.py:3: note: Revealed type is "typing.Generator[docutils.nodes.Node, None, None]"

[srittau]

Thanks, a few notes below.