resolving sage imports

[Håkan Granath]

Hi,

I am working on some Python packages which are using Sage. Up until version 10.7 everything has worked fine, but after that I never managed to get tools like pyright to resolve sage imports. My amazing new collaborator Claude found a workaround:

    Pyright reads Sage's Python sources, which also gives go-to-definition
    in the editor. Since Sage 10.9 these sources are not on the path that
    Pyright reads: Sage is installed behind an import hook, which Pyright
    cannot follow. Put them on that path once per Sage installation:

        sage -python -c "import os, site, sage.env
        pth = os.path.join(site.getsitepackages()[0], 'sage-src-for-pyright.pth')
        open(pth, 'w').write(sage.env.SAGE_SRC + '\n')"

    This only adds the directory to sys.path; at runtime Sage's import
    hook still takes precedence. Sage 10.7 needs no such step. The stubs
    in typings/ stand in for the few Sage modules that Pyright cannot read
    (compiled ones) or that come with incomplete type stubs (ZZ(n) would
    be an error); their names have type Any.

Here is an example of the stubs mentioned:

    $ cat typings/sage/rings/integer_ring.pyi
    from typing import Any

    IntegerRing: Any
    ZZ: Any
    crt_basis: Any

    def __getattr__(name: str) -> Any: ...

Now everything seems to work fine so I am happy, but I just wonder if this really is how you are supposed to do it. Have I missed something from the documentation?

Best,

Håkan Granath