VS Code与Databricks中Python/PySpark库导入路径问题排查

核心问题根源 #

你的导入问题本质是本地VS Code的Python路径配置和Databricks安装.whl后的包结构不匹配导致的，先规范包目录结构是解决问题的基础。

第一步：统一包目录结构 #

根据你遇到的导入场景，推荐两种标准结构（二选一）：

结构1：以pysparkdq作为顶层包（对应Databricks能正常导入的场景）

你的项目根目录/
├── checkenginelib/  # VS Code打开的工作目录
│   ├── pysparkdq/
│   │   ├── __init__.py  # 必须存在，标记为Python模块
│   │   └── _constraints/
│   │       ├── __init__.py
│   │       └── _Constraint.py
│   └── setup.py  # 打包配置文件

结构2：以checkenginelib作为顶层包（若要对外暴露checkenginelib前缀导入）

你的项目根目录/
├── checkenginelib/
│   ├── __init__.py
│   └── pysparkdq/
│       ├── __init__.py
│       └── _constraints/
│           ├── __init__.py
│           └── _Constraint.py
└── setup.py

第二步：配置打包文件（setup.py） #

对应结构1的setup.py示例

from setuptools import setup, find_packages

setup(
    name="pysparkdq",
    version="0.1.0",
    packages=find_packages(),  # 自动识别所有带__init__.py的模块
    install_requires=[
        "pyspark>=3.0"
    ]
)

对应结构2的setup.py示例

from setuptools import setup, find_packages

setup(
    name="checkenginelib",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        "pyspark>=3.0"
    ]
)

第三步：统一导入语句并适配VS Code路径 #

针对结构1

• 统一使用导入语句：from pysparkdq._constraints._Constraint import _Constraint
• VS Code路径配置：打开settings.json，添加以下配置让VS Code识别模块：

  "python.analysis.extraPaths": ["${workspaceFolder}"]
  

针对结构2

• 统一使用导入语句：from checkenginelib.pysparkdq._constraints._Constraint import _Constraint
• VS Code路径配置：在settings.json中添加：

  "python.analysis.extraPaths": ["${workspaceFolder}/.."]
  

第四步：测试验证 #

1. 本地生成.whl包：在setup.py所在目录执行python setup.py bdist_wheel，生成的包会存放在dist/目录下。
2. Databricks测试：将.whl上传到Databricks集群安装，用统一的导入语句验证功能。
3. VS Code调试：确认路径配置生效后，运行调试代码验证导入无报错。

注意事项 #

• 所有模块目录必须包含__init__.py，避免跨环境兼容问题。
• 不要在正式代码中硬编码sys.path添加路径，依赖VS Code配置或虚拟环境路径即可。
• 下划线开头的模块属于内部模块，建议仅在库内部调用，对外API尽量放在无下划线的模块中。

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