microsoft/pyright
1
1
Fork 0
mirror of https://github.com/microsoft/pyright.git synced 2024-08-17 03:40:44 +03:00
Code Issues Projects Releases Wiki Activity

Updated Pyright documentation for import resolution so it is more complete and better reflects the logic implemented in the code.

Browse Source
This commit is contained in:
Eric Traut 2020-07-11 12:35:05 -07:00
parent f937bb5c2d
commit 69c0841d7a
3 changed files with 32 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/configuration.md
View File

@ -18,7 +18,7 @@ Relative paths specified within the config file are relative to the config file
**stubPath** [path, optional]: Path to a directory that contains custom type stubs. Each package's type stub file(s) are expected to be in its own subdirectory. The default value of this setting is "./typings". (typingsPath is now deprecated)
**venvPath** [path, optional]: Path to a directory containing one or more subdirectories, each of which contains a virtual environment. Each execution environment (see below for details) can refer to a different virtual environment. When used in conjunction with a **venv** setting (see below), pyright will search for imports in the virtual environment’s site-packages directory rather than the paths specified in PYTHONPATH.
**venvPath** [path, optional]: Path to a directory containing one or more subdirectories, each of which contains a virtual environment. Each execution environment (see below for details) can refer to a different virtual environment. When used in conjunction with a **venv** setting (see below), pyright will search for imports in the virtual environment’s site-packages directory rather than the paths specified by the default Python interpreter.
**venv** [string, optional]: Used in conjunction with the venvPath, specifies the virtual environment to use. Individual execution environments may override this setting.

31
docs/import-resolution.md
View File

@ -1,10 +1,33 @@
# Import Resolution
Pyright resolves external imports based on several configuration settings. If a venvPath and venv are specified, these are used to locate the `site-packages` directory within the virtual environment.
## Resolution Order
If the import is relative (the module name starts with one or more dots), it resolves the import relative to the path of the importing source file.
If no venvPath is specified, Pyright falls back to the paths found in the default python interpreter’s search paths (or the python interpreter pointed to by the “python.pythonPath” setting in VS Code). Only directory-based paths are supported (as opposed to zip files or other loader packages).
For absolute (non-relative) paths, Pyright resolves imports in the following order:
The Pyright configuration file supports “execution environment” definitions, each of which can define additional paths. These are searched in addition to the venv or PYTHONPATH directories.
1. Try to resolve using a **stdlib typeshed stub**. If the `typeshedPath` is configured, use this instead of the typeshed stubs that are packaged with Pyright. This allows for the use of a newer or a patched version of the typeshed stdlib stubs.
If Pyright is reporting import resolution errors, additional diagnostic information may help you determine why. If you are using the command-line version, try adding the “--verbose” switch. If you are using the VS Code extension, look at the “Output” window (View -> Output) and choose the “Pyright” view from the popup menu.
2. Try to resolve using a local import.
a. Try to resolve relative to the **root directory of the execution environment**. If no execution environments are specified in the config file, use the root of the workspace. For more information about execution environments, refer to the [configuration documentation](https://github.com/microsoft/pyright/blob/master/docs/configuration.md#execution-environment-options).
b. Try to resolve using any of the **extra paths** defined for the execution environment in the config file. If no execution environment applies, use the `python.analysis.extraPaths` setting. Extra paths are searched in the order in which they are provided in the config file or setting.
4. Try to resolve using the **stubPath** as defined in the `stubPath` config entry or the `python.analysis.stubPath` setting.
5. Try to resolve using a **third-party typeshed** stub. If the `typeshedPath` configured, use this instead of the typeshed stubs that are packaged with Pyright. This allows for the use of a newer or a patched version of the typeshed stdlib stubs.
6. Try to resolve using the packages installed in the configured Python environment. For more details about how to configure your Python environment for Pyright, see below. If a Python environment is configured, Pyright looks in the `lib/site-packages`, `Lib/site-packages`, or `python*/site-packages` subdirectory. If no site-packages directory can be found Pyright attempts to run the configured Python interpreter and ask it for its search paths. If no Python environment is configured, Pyright will use the default Python interpreter by invoking `python`.
## Configuring Your Python Environment
Pyright does not require a Python environment to be configured if all imports can be resolved using local files and type stubs. If a Python environment is configured, it will attempt to use the packages installed in the `site-packages` subdirectory during import resolution.
Pyright uses the following mechanisms (in priority order) to determine which Python environment to use:
1. If a `venv` name is specified for the execution environment along with a `python.venvPath` setting (or a `--venv-path` command-line argument), it appends the venv name to the specified venv path.
2. If no `venv` name is specified for the execution environment but a `defaultVenv` name is specified at the top level of the config file, use that venv name instead.
3. If no `venv` or `defaultVenv` is specified in the config file, use the `python.pythonPath` setting. This setting is defined by the VS Code Python extension and can be configured using the Python extension’s environment picker interface. More recent versions of the Python extension no longer store the selected Python environment in the `python.pythonPath` setting and instead use a storage mechanism that is private to the extension. Pyright is able to access this through an API exposed by the Python extension.
4. As a fallback, use the default Python environment (i.e. the one that is invoked when typing `python` in the shell).

7
server/src/analyzer/importResolver.ts
View File

@ -139,7 +139,7 @@ export class ImportResolver {
const importName = this._formatImportName(moduleDescriptor);
const importFailureInfo: string[] = [];
// First check for a typeshed file.
// First check for a stdlib typeshed file.
if (allowPyi && moduleDescriptor.nameParts.length > 0) {
const builtInImport = this._findTypeshedPath(
execEnv,
@ -201,7 +201,7 @@ export class ImportResolver {
}
if (allowPyi) {
// Check for a stub file.
// Check for a local stub file using stubPath.
if (this._configOptions.stubPath) {
importFailureInfo.push(`Looking in stubPath '${this._configOptions.stubPath}'`);
const typingsImport = this.resolveAbsoluteImport(
@ -210,6 +210,7 @@ export class ImportResolver {
importName,
importFailureInfo
);
if (typingsImport && typingsImport.isImportFound) {
// We will treat typings files as "local" rather than "third party".
typingsImport.importType = ImportType.Local;
@ -218,7 +219,7 @@ export class ImportResolver {
}
}
// Check for a typeshed file.
// Check for a third-party typeshed file.
importFailureInfo.push(`Looking for typeshed path`);
const typeshedImport = this._findTypeshedPath(
execEnv,