如何优化Python包结构？消除导入时的src前缀冗余

是否必须保留src目录？ #

不是必须，但推荐保留——这是Python社区认可的专业包结构，能清晰区分源码与非源码资源（notebooks、data等），团队协作时更易维护。如果觉得src前缀繁琐，有两种优化方向：

方法一：本地开发时移除src前缀（快速生效） #

1. 临时给notebook添加路径 #

在notebook开头加入以下代码，将src目录加入Python模块搜索路径：

import sys
sys.path.insert(0, '../src')

之后即可直接导入目标对象：

from subpck1.A import a
# 或者
import subpck1.A as A_obj

2. 全局设置环境变量（一劳永逸） #

启动notebook前，设置PYTHONPATH环境变量，把src目录加入搜索路径：

• Linux/macOS终端：

  export PYTHONPATH="${PYTHONPATH}:./src"
  jupyter notebook
  

• Windows命令行：

  set PYTHONPATH=./src
  jupyter notebook
  

设置后，所有notebook无需额外修改路径，直接导入子包即可。

方法二：重构为标准包结构（专业长期方案） #

如果要给同事分享，建议调整为PyPI标准包格式，彻底消除src前缀：

1. 调整目录结构 #

把src目录重命名为你的包名（比如mypackage），最终结构如下：

mypackage-repo/
    data/
    notebooks/
        notebook1.ipynb
    mypackage/
        __init__.py
        subpck1/
            __init__.py
            A.py
            B.py
        subpck2/
            __init__.py
            C.py
            D.py
    pyproject.toml  # 项目配置文件

2. 优化包导出 #

在mypackage/__init__.py中直接导出常用对象，让使用者无需深入子包层级：

# mypackage/__init__.py
from .subpck1.A import a
from .subpck1.B import b  # 按需导出B中的对象
from .subpck2.C import c

3. 添加项目配置文件 #

创建pyproject.toml，让包可以通过pip安装（本地开发用可编辑模式）：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mypackage"
version = "0.1.0"
packages = ["mypackage"]

4. 安装包（本地开发） #

在仓库根目录运行：

pip install -e .

之后同事在notebook中就能直接导入：

from mypackage import a
# 或者深入子包导入
from mypackage.subpck2 import C

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