Referencing typeshed's own local stubs in editors

[Avasam]

I've had a certain annoying pain point for quite some time with typeshed stubs.

From microsoft/pylance-release#5209 :

I'd expect absolute imports to find symbols from typeshed's own stubs, and "Go to type definition" to lead to typeshed's own .pyi (when it exists) instead of the installed library.

Here's a couple example:


When new modules get added (or a new stub gets worked on, which is full of new modules):

pip install types-* inside typeshed is of limited use [...]

when the stub library, or the module, doesn't exist yet. Or even if the current module is being modified in an incompatible manner (like adding generics to class).

One option is to use relative imports, but that can lead to going up many parents, and doesn't solve the issue when writing tests (all the openpyxl tests I wrote were painful because I could not trust my editor).

Another possible solution brought by Eric Traut:

[...] Perhaps you could use an editable install when developing the stub package?

I don't have the most experience working with editable installs, but that would require writing a pyproject.toml for each stub right? Could it be done dynamically with a script?

I'd love to hear thoughts and experiences from other contributors. Especially if you use different tooling than I do (VSCode+Pylance)

Ref.: #8774

[hauntsaninja]

Maybe easier than setting up editable installs is just setting PYTHONPATH in your editor

[Avasam]

Ok so configuring python.autoComplete.extraPaths doesn't see to do anything:

    "python.autoComplete.extraPaths": [
        "${workspaceFolder}/stubs/redis"
    ]

However, there's python.envFile which defaults to ${workspaceFolder}/.env. I tried with the following content which worked:

PYTHONPATH=stubs/redis

I could change the default workspace setting to ${workspaceFolder}/.vscode/.env and create a .env file in .vscode since it's specific to that editor (same as any other vscode config). Unless someone tells me this can be reused by other editors which have similar issues.
But having to maintain the full list of stubs in there is... eh. And the path separator changes based on OS. At least it's progress and I can update it for myself.

[Avasam]

microsoft/pylance-release#5209 (comment)

After further exploration, my issue specific to redis might be due to the base library being marked as py.typed despite being very partially typed. Removing the py.typed marker in the source code fixes the linking issue to typeshed stubs.

For the new stubs networkx: It's still bundled from microsoft/python-type-stubs , deleting it from the bundled pylance stubs fixed the linking issue to local typeshed stubs.

identical openpyxl issues I had in the past: same story as networkx probably. Before it was removed from microsoft/python-type-stubs

---

1. For redis: I can see why a library marked as typed should have its own annotations prioritized over the "bundled" stubs. It's an unfortunate edge case here. But can be worked around. (relates to discussions in Remove redis (not before February 2025) #10592 (comment))
2. For stubs bundled from microsoft/python-type-stubs, I guess it'd be nice if [typeshed's local stubs] had priority here? But I'm also probably the only one who's been hitting that constantly ^^"

---

[...] I think I've just unfortunately been hitting all the specific edge cases leading me to believe this was a more widespread issue.

[Avasam]

I have created a small script for myself that indiscriminately adds all stubs to .vscode/.env. I'm sharing here for posterity, but I doubt anyone else would ever need it.

import os
from pathlib import Path


def main() -> None:
    vscodeFolder = Path(__file__).parent
    stubsFolder = vscodeFolder / ".." / "stubs"
    pythonPath = f"{os.pathsep}stubs{os.path.sep}".join(["PYTHONPATH=$PYTHONPATH", *os.listdir(stubsFolder)])
    with open(vscodeFolder / ".env", "w") as venvFile:
        venvFile.write(pythonPath)


if __name__ == "__main__":
    main()