From 29100b64df8897f2d8049571c75bfb07219b1a3e Mon Sep 17 00:00:00 2001 From: Erik De Bonte Date: Mon, 15 Jul 2024 09:04:02 -0700 Subject: [PATCH 1/2] Copy pyright docs --- TROUBLESHOOTING.md | 36 ++++++++++++------------------------ 1 file changed, 12 insertions(+), 24 deletions(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 09989bc2..eb7029b4 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -41,33 +41,21 @@ Note that if you are coming to Pylance from using the Microsoft Python Language ### Editable install modules not found -[PEP 660](https://peps.python.org/pep-0660/) enables build backends (ex. setuptools) to -use import hooks to direct the [import machinery](https://docs.python.org/3/reference/import.html) -to the package's source files rather than using a `.pth` file. Import hooks can provide -an editable installation that is a more accurate representation of your real installation. -However, because resolving module locations using an import hook requires executing Python -code, they are not usable by Pylance and other static analysis tools. Therefore, if your -editable install is configured to use import hooks, Pylance will be unable to find the -corresponding source files. - -If you want to use static analysis tools with an editable install, you should configure -the editable install to use `.pth` files instead of import hooks. See your build backend's -documentation for details on how to do this. We have provided some basic information for -common build backends below. - -#### Setuptools -Setuptools currently supports two ways to request -["compat mode"](https://setuptools.pypa.io/en/latest/userguide/development_mode.html#legacy-behavior) -where a `.pth` file will be used -- a config setting and an environment variable. Another -option is ["strict mode"](https://setuptools.pypa.io/en/latest/userguide/development_mode.html#strict-editable-installs) -which uses symlinks instead. - -#### Hatch/Hatchling -[Hatchling](https://hatch.pypa.io/latest/config/build/#dev-mode) uses `.pth` files by +If you want to use static analysis tools with an editable install, you should configure the editable install to use `.pth` files that contain file paths rather than executable lines (prefixed with `import`) that install import hooks. See your package manager’s documentation for details on how to do this. We have provided some basic information for common package managers below. + +Import hooks can provide an editable installation that is a more accurate representation of your real installation. However, because resolving module locations using an import hook requires executing Python code, they are not usable by Pyright and other static analysis tools. Therefore, if your editable install is configured to use import hooks, Pyright will be unable to find the corresponding source files. + +#### pip / setuptools +`pip` (`setuptools`) supports two ways to avoid import hooks: +- [compat mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html#legacy-behavior) +- [strict mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html#strict-editable-installs) + +#### Hatch / Hatchling +[Hatchling](https://hatch.pypa.io/latest/config/build/#dev-mode) uses path-based `.pth` files by default. It will only use import hooks if you set `dev-mode-exact` to `true`. #### PDM -[PDM](https://pdm.fming.dev/latest/pyproject/build/#editable-build-backend) uses `.pth` +[PDM](https://pdm.fming.dev/latest/pyproject/build/#editable-build-backend) uses path-based `.pth` files by default. It will only use import hooks if you set `editable-backend` to `"editables"`. From 1524835a254def972ad7018fc3dbdd9d7ffcd4d4 Mon Sep 17 00:00:00 2001 From: Erik De Bonte Date: Mon, 15 Jul 2024 09:06:02 -0700 Subject: [PATCH 2/2] Replace Pyright with Pylance --- TROUBLESHOOTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index eb7029b4..f5c460cb 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -43,7 +43,7 @@ Note that if you are coming to Pylance from using the Microsoft Python Language If you want to use static analysis tools with an editable install, you should configure the editable install to use `.pth` files that contain file paths rather than executable lines (prefixed with `import`) that install import hooks. See your package manager’s documentation for details on how to do this. We have provided some basic information for common package managers below. -Import hooks can provide an editable installation that is a more accurate representation of your real installation. However, because resolving module locations using an import hook requires executing Python code, they are not usable by Pyright and other static analysis tools. Therefore, if your editable install is configured to use import hooks, Pyright will be unable to find the corresponding source files. +Import hooks can provide an editable installation that is a more accurate representation of your real installation. However, because resolving module locations using an import hook requires executing Python code, they are not usable by Pylance and other static analysis tools. Therefore, if your editable install is configured to use import hooks, Pylance will be unable to find the corresponding source files. #### pip / setuptools `pip` (`setuptools`) supports two ways to avoid import hooks: