Python如何仅通过模块文件名导入 省略完整包层级路径

现有冗余实现 #

if __name__ == "__main__":
  from SettingsHandler import YamlParser
  from UIComponents.IncrementSlider import IncrementSlider
  from UIComponents.ToggleSwitch import ToggleSwitch
  from UI.SettingsPane import SettingsPane
  #from KeyStrokeWrapper import KeyStrokeWrapper
else:
  from Handlers.SettingsHandler import YamlParser
  from Handlers.KeyStrokeWrapper import KeyStrokeWrapper
  from Handlers.UIComponents.IncrementSlider import IncrementSlider
  from Handlers.UIComponents.ToggleSwitch import ToggleSwitch
  from Handlers.UI.SettingsPane import SettingsPane

问题核心是脚本直接运行、作为模块被导入两种场景下，Python模块搜索路径不一致，导致必须写两套导入逻辑，重复维护多级包路径成本高。以下是可落地的解决方法：

方法1：统一项目结构+固定入口（推荐用于正式项目） #

这是最符合Python包规范的方案，不需要写任何分支判断逻辑：

• 把所有业务代码全部收拢到Handlers包目录下，不要在包同级目录存放需要导入的业务脚本
• 在项目根目录（和Handlers文件夹同级）新建固定启动入口，比如main.py
• 所有导入统一从Handlers根路径开始写，包内模块互相导入使用相对路径

# 项目根目录/main.py
from Handlers.SettingsHandler import YamlParser
from Handlers.KeyStrokeWrapper import KeyStrokeWrapper
from Handlers.UIComponents.IncrementSlider import IncrementSlider
from Handlers.UIComponents.ToggleSwitch import ToggleSwitch
from Handlers.UI.SettingsPane import SettingsPane

if __name__ == "__main__":
    # 写入程序启动逻辑
    pass

包内模块比如Handlers/UIComponents/IncrementSlider.py需要导入其他模块时，直接用相对导入即可，不用关心运行路径：

# 导入同目录下的ToggleSwitch
from .ToggleSwitch import ToggleSwitch
# 导入上层目录的SettingsHandler
from ..SettingsHandler import YamlParser

方法2：包根统一导出+路径配置实现短名导入 #

如果想要实现import IncrementSlider这类不带多级路径的导入效果，可以分两步配置：

1. 在Handlers/__init__.py中提前导出所有公共模块和类，避免重复写多级路径

# Handlers/__init__.py
from Handlers.SettingsHandler import YamlParser
from Handlers.KeyStrokeWrapper import KeyStrokeWrapper
from Handlers.UIComponents.IncrementSlider import IncrementSlider
from Handlers.UIComponents.ToggleSwitch import ToggleSwitch
from Handlers.UI.SettingsPane import SettingsPane

配置完成后，所有场景下都可以直接从包根导入需要的对象，不用写完整层级：

from Handlers import IncrementSlider, ToggleSwitch, YamlParser

2. 如果还要省略Handlers前缀，在程序最启动的位置把Handlers目录加入Python搜索路径即可

# 所有导入逻辑之前执行
import sys
from pathlib import Path
sys.path.append(str(Path(__file__).parent / "Handlers"))

# 之后就可以直接用模块名导入
from IncrementSlider import IncrementSlider
from ToggleSwitch import ToggleSwitch

注意：直接修改sys.path的方式仅适合自用脚本，不适合对外发布的开源库，容易引发同名模块冲突、导入顺序异常问题。

方法3：单分支路径配置消除重复导入 #

如果暂时不想调整现有目录结构，也不用写两套导入逻辑，只需要在分支中统一配置搜索路径，后续只保留一套导入代码即可：

import sys
from pathlib import Path
if __name__ == "__main__":
    # 直接运行脚本时，把Handlers目录加入搜索路径
    sys.path.append(str(Path(__file__).parent / "Handlers"))

# 后续仅需写一套导入，两种运行场景通用
from SettingsHandler import YamlParser
from KeyStrokeWrapper import KeyStrokeWrapper
from UIComponents.IncrementSlider import IncrementSlider
from UIComponents.ToggleSwitch import ToggleSwitch
from UI.SettingsPane import SettingsPane

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