含多Python入口点及内部依赖的项目最佳目录结构咨询

采用Python官方推荐的入口点（Entry Points）机制，配合规范的包结构调整，既能清理顶层目录，又能解决导入问题，同时保持各脚本的独立性，具体步骤如下：

1. 调整项目目录结构 #

将原有的package1、package2和所有mainX.py统一放到一个顶层包下，推荐使用src布局（避免命名冲突，符合Python打包规范），调整后结构如下：

project/
    src/
        myproject/  # 自定义顶层包名，可根据项目名称修改
            package1/
                __init__.py
                module1.py
                module2.py
            package2/
                __init__.py
                module1.py
                module2.py
            cli/  # 存放原mainX.py的子包
                __init__.py
                main1.py
                main2.py
                ...
                mainN.py
    pyproject.toml  # 项目配置文件

2. 改造原mainX.py脚本 #

将每个mainX.py中的执行逻辑封装成main()函数，同时修改导入路径为顶层包的绝对导入，以main1.py为例：

from myproject.package1 import module1
from myproject.package2 import module2

def main():
    # 原main1.py的所有执行逻辑
    pass

# 保留直接运行的能力，方便开发调试
if __name__ == "__main__":
    main()

3. 配置入口点 #

在pyproject.toml中配置console_scripts类型的入口点，将每个mainX.py的main()函数映射为命令行可执行命令：

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

[project]
name = "myproject"
version = "0.1.0"
packages = ["myproject"]
package_dir = {"": "src"}  # 告知setuptools包在src目录下

[project.entry-points."console_scripts"]
main1 = "myproject.cli.main1:main"
main2 = "myproject.cli.main2:main"
# 依次添加所有mainX对应的映射关系

4. 开发与使用方式 #

• 开发阶段：在项目根目录执行pip install -e .，以可编辑模式安装项目，之后就能直接在命令行输入main1、main2等命令执行对应脚本；也可以用python -m myproject.cli.main1直接运行调试。
• 分发阶段：打包后用户安装项目时，这些命令会自动添加到系统的可执行路径中，直接调用即可。

方案优势 #

• 完全符合Python打包规范，规避手动修改sys.path带来的隐患
• 各脚本保持独立，无需耦合到单入口点的子解析器
• 顶层目录仅保留配置文件，结构整洁
• 开发和分发流程统一，无需额外复杂操作

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