17370845950

Python项目结构需立足模块导入、包初始化、路径解析和可安装性四支柱；__init__.py定义包边界并导出接口，-m运行确保相对导入正确，pyproject.toml声明依赖与入口，src/布局隔离代码与非代码文件。

Python项目结构不是随便建几个文件夹就行，关键在理解模块导入、包初始化、路径解析和可安装性这四根支柱。光会写代码不够，项目一打包就报错、本地能跑线上挂掉、别人拉下来根本不会用——这些问题全出在结构设计上。

包与模块的边界必须靠__init__.py来定义

它不只是历史遗留文件，而是Python识别“包”的唯一凭证。空文件也生效，但真正价值在于显式导出接口：

• 在mylib/__init__.py里写from .core import process_data，外部就能直接import mylib; mylib.process_data()
• 用__all__ = ["process_data"]控制from mylib import *能导入什么，避免污染命名空间
• 别把业务逻辑塞进__init__.py——它该轻量，只做声明和简单组装

导入路径问题本质是sys.path和当前工作目录的博弈

运行python main.py和python -m mypackage.main行为完全不同：

• 前者以main.py所在目录为起点，相对导入容易失败
• 后者以项目根目录为起点，from .utils import helper才能正确解析
• 调试时加print(sys.path)看路径顺序，临时加路径用sys.path.insert(0, "/abs/path/to/src")，但上线前必须改成可安装模式

让项目真正“可安装”，绕不开pyproject.toml

告别setup.py，用现代标准声明依赖和入口：

• [build-system]指定构建器（如setuptools或hatchling）
• [project]写明name、version、dependencies和requires-python
• [project.entry-points."console_scripts"]注册命令行工具，比如mytool = "mylib.cli:main"
• 装本地包：执行pip install -e .（开发模式），所有导入立即生效，改完代码不用重装

典型稳健结构长这样，不是教条而是经过压测的惯用法

以中等规模工具类项目为例：

• src/——源码根目录（隔离测试/配置等非代码文件）
• src/mytool/——实际包，含__init__.py、cli.py、core/子包
• tests/——与src/平级，用pytest自动发现
• pyproject.toml——在项目最外层，管理整个生命周期
• 不放__pycache__、.env、venv/到Git，靠.gitignore守住底线