python项目结构设计核心是“可维护、可测试、可部署”，需按职责分层：src/为源码根目录，tests/与之镜像，config/、data/、scripts/物理隔离，依赖分层管理，入口与文档自成体系。
Python项目结构设计核心是“可维护、可测试、可部署”，不是堆文件夹，而是按职责分层、隔离关注点。一个规范的结构能让新成员快速上手，CI流程稳定运行，打包发布不踩坑。
src/ 作为源码根目录（推荐）
避免把模块直接放在项目根目录下（即 不推荐 myproject/ 下直接放 main.py 或 utils.py）。应统一收口到 src/ 中：
-
src/myproject/—— 实际包目录，含__init__.py，所有业务代码、子模块都在此 -
pyproject.toml中配置[project]的requires-python和dependencies，并设[build-system]使用setuptools或hatchling - 安装时用
pip install -e .（开发模式），工具会自动识别src/为源码起点，避免本地路径污染
分离配置、数据与代码
运行时依赖项不能硬编码，需物理隔离：
-
config/：存放base.py、dev.py、prod.py，用os.getenv()或pydantic-settings加载环境变量覆盖 -
data/：只读数据文件（如 CSV、JSON 样本）、模型权重（若小）、缓存目录（data/cache/）—— 不提交大文件，加.gitignore -
scripts/：非核心但需手动执行的脚本，如数据清洗、DB 初始化，不作为包导入使用
测试与依赖明确分层
测试不是附属，而是工程一等公民：
立即学习“Python免费学习笔记（深入）”；
-
tests/与src/平级，结构镜像（如tests/test_api/对应src/myproject/api/） - 用
pytest+pytest-cov，在pyproject.toml中配[tool.pytest.ini_options]指定testpaths = ["tests"] -
requirements/下拆分依赖：base.txt（核心）、dev.txt（含black,mypy）、test.txt（含pytest,responses）
入口、构建与文档自成体系
让项目“开箱即用”：
-
app.py或cli.py放在项目根（非src内），作为 CLI 入口，仅做参数解析和调度，不写业务逻辑 -
Makefile或justfile封装常用命令：make test、make format、make build，降低协作门槛 -
docs/存放mkdocs.yml和源文件；README.md包含快速启动、环境要求、核心命令三要素
