From b4a158f48a92bf6ee3da930d4e38184c28c15ca9 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 4 Sep 2025 09:13:18 +0200 Subject: [PATCH] Clarify editable install behavior with setuptools and uv (#10888) * Clarify editable install behavior with setuptools and uv Following a user question in uv (https://github.com/astral-sh/uv/issues/15652), clarify the documentation around editables. From my uv experience, import hooks breaking static type checkers is almost exclusively a setuptools problem (see e.g. https://github.com/astral-sh/uv/issues/1708#issuecomment-2174463476 and https://github.com/astral-sh/uv/issues/3898), so I clarified the docs that this is update using uv with setuptools. * Update docs/import-resolution.md Co-authored-by: DetachHead <57028336+DetachHead@users.noreply.github.com> * Remove "generally" --------- Co-authored-by: DetachHead <57028336+DetachHead@users.noreply.github.com> --- docs/import-resolution.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/import-resolution.md b/docs/import-resolution.md index ff1413534..658d90936 100644 --- a/docs/import-resolution.md +++ b/docs/import-resolution.md @@ -41,25 +41,27 @@ Pyright uses the following mechanisms (in priority order) to determine which Pyt 3. As a fallback, use the default Python environment (i.e. the one that is invoked when typing `python` in the shell). ### Editable installs - -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. +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. 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: +Notably, setuptools uses import hooks by default. For setuptools-based editable installs to be usable with Pyright, setuptools needs to be configured to use path-based `.pth` files through the build frontend. + +#### pip with setuptools +`pip` with `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) -#### uv -[uv](https://docs.astral.sh/uv/reference/settings/#config-settings) can be -configured to avoid import hooks with +#### uv with setuptools +When using uv with setuptools, uv can be [configured](https://docs.astral.sh/uv/reference/settings/#config-settings) to avoid import hooks: ```toml [tool.uv] config-settings = { editable_mode = "compat" } ``` +The `uv_build` backend always uses path-based `.pth` files. + #### 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`.