大型Python项目模块组织咨询：顶层公共模块导入难题

核心方案：可安装包结构+绝对导入 #

这是Python官方推荐的大型项目组织方式，彻底解决跨目录导入问题：

1. 规整项目结构
   按功能分层搭建目录，顶层创建与项目同名的包目录，每个子目录添加__init__.py（Python3.3+可省略，但显式添加更便于后续模块导出）。示例结构：

   my_project/
   ├── pyproject.toml  # 或setup.py，用于项目打包
   └── my_project/
       ├── __init__.py
       ├── core/
       │   ├── __init__.py
       │   └── rotation.py  # 存放通用旋转矩阵类
       └── objects/
           ├── __init__.py
           └── 3d/
               ├── __init__.py
               └── cube.py  # 需要导入旋转矩阵的子模块
   

2. 使用绝对导入
   在子模块（比如cube.py）中直接通过顶层包名导入基础模块：

   from my_project.core.rotation import RotationMatrix
   

   这种方式不受脚本运行位置影响，只要项目在Python环境路径中，就能正常导入。

3. 开发阶段用可编辑安装
   无需修改sys.path，在项目根目录（外层my_project）执行以下命令，将项目以可编辑模式安装到Python环境：

   pip install -e .
   

   这会在site-packages中创建项目链接，代码修改后无需重新安装，子模块即可直接使用绝对导入。

辅助建议 #

• 避免依赖相对导入：虽然Python支持from ...core.rotation import RotationMatrix这类相对导入，但它仅能在包内部使用，直接运行子模块脚本会触发导入错误，大型项目中绝对导入更稳定。
• 采用现代打包配置：用pyproject.toml替代传统setup.py，这是PEP 621推荐的标准打包方式，示例配置：

  [build-system]
  requires = ["setuptools>=61.0"]
  build-backend = "setuptools.build_meta"
  
  [project]
  name = "my_project"
  version = "0.1.0"
  

• 按功能拆分模块：把通用基础代码放在core或utils目录，业务逻辑按领域拆分（比如objects/3d、rendering等），便于维护和扩展。

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