Clarify editable install behavior with setuptools and uv#10888
Clarify editable install behavior with setuptools and uv#10888erictraut merged 3 commits intomicrosoft:mainfrom
Conversation
Following a user question in uv (astral-sh/uv#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. astral-sh/uv#1708 (comment) and astral-sh/uv#3898), so I clarified the docs that this is update using uv with setuptools.
Co-authored-by: DetachHead <57028336+DetachHead@users.noreply.github.com>
docs/import-resolution.md
Outdated
| ### 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. Only setuptools is known to use import hooks by default, other build backends generally default to path-based `.pth` files. |
There was a problem hiding this comment.
Are you sure this problem is limited to setuptools? I'm not confident of this, but I don't have specific examples off the top of my head. Perhaps someone from the pylance team could confirm (@rchiodo).
There was a problem hiding this comment.
AFAIK other tools do use import hooks.
Hatch and uv don't, but a bunch of others do.
Here's what copilot gave me when asked for other tools that generate import hooks:
🔍 Tools That Create or Use Python Import Hooks
This table summarizes tools and libraries that implement or rely on Python import hooks, typically by modifying sys.meta_path or using custom loaders. These hooks enable dynamic behavior during module import, such as loading non-Python files, transforming code, or injecting runtime logic.
| Tool / Library | Purpose / Use Case | Mechanism | Link |
|---|---|---|---|
| custom-imports | Import config files (.ini, .json, .csv) as Python modules |
Registers custom importers via sys.meta_path |
PyPI |
| imphook | Lightweight framework for per-file-type import hooks | Custom MetaPathFinder and loaders |
GitHub |
| importlib | Standard library foundation for building custom import hooks | Implement MetaPathFinder, PathEntryFinder, etc. |
Stack Overflow guide |
| pyximport | Automatically compiles and imports .pyx Cython files |
Adds hook to sys.meta_path |
Cython docs |
| zipimport / pkgutil / runpy | Built-in modules that use import hooks internally for zipped packages and dynamic execution | Custom loaders and finders | zipimport docs |
| pluggy / stevedore | Dynamically discover and load plugins | Entry point scanning, sometimes with import hooks | Pluggy docs |
🧠 Notes
- Most tools use
sys.meta_pathto register custom finders/loaders. - Import hooks are powerful for plugin systems, config injection, and non-standard module formats.
- Setuptools used to embed Python code in
.pthfiles for import-time behavior, but modern tools like Hatch and uv avoid this.
docs/import-resolution.md
Outdated
| ### 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. Only setuptools is known to use import hooks by default, other build backends generally default to path-based `.pth` files. |
There was a problem hiding this comment.
Nit: The phrase "other build backends..." should be a separate sentence.
Also, I recommend removing "generally" because it's ambiguous in this context. Does it mean that they sometimes don't default to path-based files? Does it mean that a small subset of them don't? If we're confident that setuptools is the only one, then we should say that. If we're not confident of this, then we should probably not call out setuptools specifically.
There was a problem hiding this comment.
In my user support experience in uv, the problems I saw were always setuptools. That doesn't mean other build backends can't do this, but so far as a gotcha that needs to be specifically documented I've only seen it from setuptools.
|
Thanks for the update. Looks good. |
Following a user question in uv (astral-sh/uv#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. astral-sh/uv#1708 (comment) and astral-sh/uv#3898), so I clarified the docs that this is update using uv with setuptools.