如何基于多子模块创建Python库？分层导入问题求助

看起来你在构建带多子模块的Python库时踩了导入路径的坑——这种问题在新手搭建分层包结构时太常见了，我帮你梳理下核心问题和解决步骤：

第一步：先确认你的库结构是否规范 #

首先，你的库目录结构应该是这样的（如果不是，先调整）：

your_project/
├── setup.py
└── package_name/
    ├── __init__.py
    ├── submodule1/
    │   ├── __init__.py
    │   └── (你的子模块代码文件，比如core.py)
    └── submodule2/
        ├── __init__.py
        └── (子模块2的代码文件)

注意：setup.py必须和你的根包目录package_name同级，不能放在package_name里面。

第二步：修正子模块的__init__.py #

子模块的__init__.py的作用是对外暴露需要让用户使用的类/函数，而不是写全部逻辑。比如submodule1/__init__.py可以这么写：

# 从子模块内部的代码文件导入需要暴露的内容
from .core import Submodule1Class, submodule1_function

这样用户导入submodule1时，就能直接拿到这些内容，不用深入到内部文件。

第三步：调整根包的__init__.py #

根目录的__init__.py决定了用户导入package_name时能直接访问到什么。如果希望用户能通过package_name.submodule1访问子模块，就在根__init__.py里显式导入子模块：

# 导入所有子模块，让用户可以直接调用 package_name.submodule1
from . import submodule1, submodule2

# 可选：如果想让用户更方便，直接把模块内的内容导出到根命名空间
# 比如用户可以直接 from package_name import Submodule1Class
from .submodule1 import Submodule1Class, submodule1_function
from .submodule2 import Submodule2Class, submodule2_function

第四步：修复setup.py的关键配置 #

你的setup.py最大的问题大概率是没有正确识别所有子模块。别手动写packages列表，用setuptools的find_packages()自动发现，这样不会遗漏子模块：

from setuptools import setup, find_packages

setup(
    name="package_name",
    version="0.1.0",
    packages=find_packages(),  # 自动扫描所有子模块
    author="你的名字",
    description="你的库描述",
    # 其他可选配置：比如python_requires, install_requires等
)

第五步：正确安装库（这步最容易被忽略！） #

不要直接在库目录下运行iPython或者脚本——这样Python会把当前目录加入sys.path，导致导入路径混乱。你需要用开发模式安装你的库：

# 切换到setup.py所在的目录
cd /path/to/your_project
# 开发模式安装，修改代码后无需重新安装
pip install -e .

常见错误的快速修复 #

• 如果iPython报错ImportError: cannot import name 'submodule1' from 'package_name'：检查根__init__.py是否有from . import submodule1，同时确认submodule1/__init__.py没有语法错误。
• 如果报错ModuleNotFoundError: No module named 'submodule1'：确保你是通过from package_name import submodule1导入，而不是直接import submodule1；同时确认已经用pip install -e .安装了库。

测试导入 #

安装完成后，在iPython里测试：

import package_name

# 测试子模块访问
package_name.submodule1.Submodule1Class()

# 如果根__init__导出了内容，也可以直接用
package_name.Submodule1Class()

这样应该就能解决你的分层导入问题了。

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