Improve pyi file import

[mhils]

refs #731

@apparebit: Could you please check if this fixes your issue? I've tried following your repro steps, but this fails when running ./rr.sh the second time (maturin: not found).

[apparebit]

I installed the wheel generated by CI and it does fix the bug I reported.

However, it also surfaces another bug, at least from what I can tell. The typing stubs for pretttypretty contain a good number of self- and forward references. Pylance has no issue with them and they all type check. Mypy's stubgen tool generates stubs like that as well. Hence, I do believe that's acceptable. Alas PEP 484 uses lots of words to say very little beyond stub files having the "same syntax as regular Python modules." Since pdoc seems to be evaluating the stubs like a regular module loader would, self- and forward references cause errors because no binding can be found. Why does pdoc execute stubs? As a convenience for inspecting the declarations?

[apparebit]

./rr.sh install uses Rustup to install the Rust tool chain. In turn, Rustup modifies most shell initialization files such as .profile and .bashrc to update the PATH like so:

export PATH="$HOME/.cargo/bin:$PATH"

The install step should have printed a warning to restart your shell to pick up the changes to the PATH. Can you please check whether the shell initialization files were updated? I want to make sure the runner script is as robust as possible.

[mhils]

I installed the wheel generated by CI and it does fix the bug I reported.

Thanks for verifying!

Why does pdoc execute stubs? As a convenience for inspecting the declarations?

pdoc is fundamentally based on dynamic analysis, and that extends to pyi files as well. I don't want to maintain a full-blown static analyzer for Python-like files, so dynamic execution is the best we can do. On the upside, you can typically make forward references work with

from __future__ import annotations

at the top of your Python file.

The install step should have printed a warning to restart your shell to pick up the changes to the PATH.

It did, but I didn't pay attention and blindly followed your steps. Thanks for clarifying, seems to work otherwise!

[apparebit]

Right, but even an execution-based dynamic analysis can support self- and forward-references rather easily:

1. Extract the names and possibly kinds of all module-level bindings, i.e., the def, class, and variable definitions.
2. Create a binding to a dummy value for each of the names in the dictionary serving as module environment.
3. exec as before.

The dummy bindings ensure that lookups during evaluation don't fail. But by the end of module evaluation all dummy bindings have been replaced with real ones. I even seem to remember that some Python standard library module implements the name extraction already. I'll have a look tomorrow.

[mhils]

Happy to take a look at patches. :)