Document which paths are searched by autoSearchPaths and make that list configurable

[koenlek]

Currently, the documentation of python.analysis.autoSearchPaths says:

Used to automatically add search paths based on some predefined names (like src).

With pylance being closed source, it seems impossible to know what list of predefined names it checks... Could we make documentation explicit on the list of paths it automatically checks?

Additionally, can we make that list configurable? Perhaps it's already configurable by means of python.analysis.extraPaths, but the documentation on that is unclear on whether it allows wildcards (e.g. "**/python"). If wildcards are allowed for that, please make that clear in the docs too.

Also, the relationship to pyright and the possibility to configure pyright directly could probably also be better documented.

Thanks!

[jakebailey]

With pylance being closed source, it seems impossible to know what list of predefined names it checks... Could we make documentation explicit on the list of paths it automatically checks?

This code is here: https://github.com/microsoft/pyright/blob/295db6af56c36cb11b41f35d2032050a7e85fcf2/packages/pyright-internal/src/common/configOptions.ts#L1457

It's only src at the moment, but its intent is that we could add more. We haven't found that more than src is needed, however, and recommend setting extraPaths if it isn't working for you by default.

If wildcards are allowed for that, please make that clear in the docs too.

Wildcards are not currently allowed for extraPaths. See #973. (If we support it, we document it; other options in the below linked docs do.)

Also, the relationship to pyright and the possibility to configure pyright directly could probably also be better documented.

The relationship is documented in our FAQ: https://github.com/microsoft/pylance-release/blob/main/FAQ.md

Configuration documentation for pyright is hosted in the pyright repo: https://github.com/microsoft/pyright/blob/main/docs/configuration.md

[koenlek]

Thanks for the fast reply + pointing out the docs! Just adding "py" and "python" to this list would make a huge difference for the large repos I'm working with. Would it be ok if I open a PR for that?

It seems like extraPaths with wildcards (#973) is going to be the perfect solution for our use case though. Fingers crossed for that to land!

[jakebailey]

I'm not sure we'd want to do that; we settled on the current form based on a survey of popular projects, and we're currently working on other improvements to better handle imports in other ways (#68, for example).

What is the structure of your project? Is extraPaths not a good fit for you?

[koenlek]

Ok, I'll just put my hopes on #973 then.

[jakebailey]

Sure, though I would still appreciate some info about your usecase; autoSearchPaths is a solution, but I'm moreso trying to understand what it is that you're facing.

[koenlek]

For example, when working with a large monorepo, python code can be scattered over multiple places. This way, the extraPaths list can end up consisting of hundreds of items, whereas wildcards could probably capture >90% of those already.

Note that an alternative solution to providing a long list of extraPaths is to link everything together in a venv, but then vscode can end up opening multiple copies of files: at the symlinked path in the venv and at the original path (I've opened a vscode feature request with a proposed solution for that here: microsoft/vscode#130082)...

[jakebailey]

I see; are they individual projects such that a multi-root workspace may work better, or are they interdependent so that they need to be able to import each other?

[koenlek]

The latter

[jakebailey]

Okay, thanks. I think that #973 is going to be the thing, then.