Python编辑器自动补全为何未忽略私有导入与__all__限制？

问题现象 #

你在自定义模块中用__all__定义公共成员，同时将依赖导入标记为私有前缀（如_use_dependency），但VSCode和PyCharm的自动补全依然会显示这些私有导入；而标准库（如random）采用同样的写法，私有导入却不会出现在补全列表中。

示例代码：

dependency.py #

def use_dependency():
    pass

manager.py #

from dependency import use_dependency as _use_dependency

__all__ = ["get_stuff", "write_stuff"]

def get_stuff():
    return "stuff"

def write_stuff(stuff):
    print(f"Writing {stuff}")

main.py #

import manager
# IDE补全会提示manager._use_dependency()，但这是预期外的私有成员
manager._use_dependency()

而标准库random的源码中大量使用私有前缀导入，但补全不会显示这些私有名称：

from warnings import warn as _warn
from math import log as _log, exp as _exp, pi as _pi
# 其他私有导入...

核心原因 #

1. 标准库的存根文件机制
   标准库模块几乎都配有类型存根文件（.pyi），IDE在做自动补全时会优先读取存根文件中的定义，而非直接解析源码。存根文件里只会列出__all__中声明的公共成员，完全忽略源码里的私有导入，所以你看不到这些私有名称。

2. 自定义模块的解析逻辑
   自定义模块默认没有存根文件，IDE会直接解析模块的顶层命名空间——所有在模块顶层定义或导入的名称（哪怕是以_开头的私有成员）都会被IDE识别并加入补全列表。__all__的作用只是限制from module import *时导入的成员，并不会直接影响IDE的自动补全规则。

解决方法 #

1. 添加类型存根文件 #

给自定义模块创建对应的.pyi存根文件，只在其中定义公共成员，IDE会优先读取存根内容，忽略源码中的私有导入。

比如为manager.py创建manager.pyi：

__all__ = ["get_stuff", "write_stuff"]

def get_stuff() -> str: ...
def write_stuff(stuff: str) -> None: ...

2. 移除非必要的顶层私有导入 #

如果私有导入仅在模块内部的函数中使用，可以将其移到函数内部，避免暴露在模块顶层命名空间：

__all__ = ["get_stuff", "write_stuff"]

def get_stuff():
    from dependency import use_dependency
    use_dependency()
    return "stuff"

# 其他函数...

3. 手动删除私有名称 #

在模块末尾使用del语句移除私有导入的名称，这样它们会从模块的顶层命名空间中消失，IDE自然不会显示：

from dependency import use_dependency as _use_dependency

__all__ = ["get_stuff", "write_stuff"]

# 模块函数定义...

# 删除私有名称
del _use_dependency

内容的提问来源于stack exchange，提问作者Aram Darakchian