`TYPE_CHECKING` warnings when subclassing `textual` objects

[mrossinek]

Problem Description

I am seeing the same problem reported in #648 but when dealing with classes from the textual package. I am using the latest pdoc (14.5.0) so the fix from #649 does not appear to have resolved this for all potential third-party packages.

I am not sure what could be different about textual that would potentially cause this behavior to differ from the other case.

Steps to reproduce the behavior:

1. Create a new Python venv and install pdoc==14.5.0 and textual==0.63.5.
2. Save the following contents to pdoc-bug-695.py:

from textual.widgets import Static

class Foo(Static):
    ...

3. Run pdoc pdoc-bug-695.py and observe the warnings upon loading the HTML page:

Warn: Failed to run TYPE_CHECKING code while parsing dict[type[Message], list[tuple[Callable, str | None]]] type annotation for textual.dom.DOMNode._decorated_handlers: No module named '_typeshed' (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:132)
Warn: Error parsing type annotation dict[type[Message], list[tuple[Callable, str | None]]] for textual.dom.DOMNode._decorated_handlers. Import of Message failed: name 'Message' is not defined (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:148)
Warn: Failed to run TYPE_CHECKING code while parsing Sequence['Widget'] type annotation for pdoc-bug-695.Foo.children: No module named '_typeshed' (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:132)
Warn: Error parsing type annotation Sequence['Widget'] for pdoc-bug-695.Foo.children. Import of Widget failed: name 'Widget' is not defined (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:148)
Warn: Failed to run TYPE_CHECKING code while parsing 'Screen[object]' type annotation for pdoc-bug-695.Foo.screen: No module named '_typeshed' (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:132)
Warn: Error parsing type annotation 'Screen[object]' for pdoc-bug-695.Foo.screen. Import of Screen failed: name 'Screen' is not defined (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:148)
Warn: Failed to run TYPE_CHECKING code while parsing list[Widget] type annotation for pdoc-bug-695.Foo.displayed_children: No module named '_typeshed' (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:132)
Warn: Error parsing type annotation list[Widget] for pdoc-bug-695.Foo.displayed_children. Import of Widget failed: name 'Widget' is not defined (/home/max/sandbox/python/.direnv/python-3.12/lib/python3.12/site-packages/pdoc/doc_types.py:148)

System Information

Paste the output of "pdoc --version" here.

pdoc: 14.5.0
Python: 3.12.3
Platform: Linux-6.9.1-arch1-2-x86_64-with-glibc2.39

[mhils]

We probably need to get https://github.com/python/typeshed/tree/main/stdlib/_typeshed into pdoc for this somehow.

[mrossinek]

From my understanding, that requires TYPE_CHECKING = True which is what static type checkers set (although I don't know how exactly they do that). Is that something that could work for pdoc?

[mhils]

We already try to evaluate the TYPE_CHECKING blocks, this is where the error is coming from. We're missing the _typeshed package import in those sections

[mrossinek]

I meant to suggest that maybe pdoc can act like a static type checker where TYPE_SETTING = True which should lead to _typeshed being available, right? Maybe I am also misunderstanding how this works exactly.

[mhils]

pdoc does do that, in a way we already try to set TYPE_SETTING = True. But the _typeshed module is not in your typical Python install, which is why the import fails.

[mhils]

More specifically: I think we need to vendor the _typeshed from the link above, and make it available as _typeshed during evaluation.

[mhils]

It turns out that vendoring isn't easy, _typeshed/__init__.pyi also bails on import here.