setuptools配置错误致pip安装后无法导入包及子包问题排查

存在两个核心配置/代码错误，导致安装后包无法被正常识别、导入逻辑失效：

• setup.py的src目录布局配置错误，没有正确将包内容打包到安装路径，安装完成后site-packages目录下不存在合法的package包实体，直接触发ModuleNotFoundError
• 包内部跨模块导入写法不规范，使用了依赖运行时工作目录的裸导入，即使包安装正确，运行时也会找不到子模块

注：本地直接执行python3 src/package能正常运行，是因为Python会自动将当前执行的包路径加入sys.path，此时package1/package2会被临时识别为顶层模块，属于特殊路径下的偶然生效，不代表打包配置正确。

1. 修正setup.py打包配置 #

标准src布局的包，需要将根包查找路径指向src目录，同时自动发现所有子包，替换原有配置如下：

import setuptools

setuptools.setup(
    name="package",
    version="1.0.0",
    python_requires='>=3.8',
    # 声明所有顶层包都在src目录下查找
    package_dir={"": "src"},
    # 自动扫描src目录下的所有Python包，避免漏写子包
    packages=setuptools.find_packages(where="src"),
)

原有配置package_dir={"package": "src"}的逻辑是“把package包的内容映射到src目录”，会导致打包时把src下的package子文件夹直接装到site-packages的package路径下，最终安装后的包结构缺少__init__.py等核心文件，无法被Python识别为合法包。

2. 修正包内不规范的导入语句 #

所有包内部的跨模块导入，必须使用显式相对导入，或者携带顶层包名的绝对导入，禁止直接写裸子包名：

• 修改src/package/__main__.py：

from . import package2
from .package2.module2 import function2

if __name__ == '__main__':
    function2()
    print("Hello from main")

• 修改src/package/package2/module2.py：

from . import package1
from .package1.module1 import function1

def function2():
    function1()
    print("Hello from function2")

其余__init__.py文件中的相对导入写法正确，无需修改。

1. 先清理之前错误安装的版本：

pip uninstall -y package

2. 在项目根目录（setup.py所在路径）重新执行安装：

pip install .

3. 切换到任意非项目路径，编写测试脚本：

import package
package.package2.module2.function2()

运行后将得到预期输出：

Hello from function1
Hello from function2

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