典型的 Python 项目结构

一个通用的 Python 包（Package） 的文件结构，通常遵循一定的组织规范，以便于开发、测试、部署和维护。这种结构不仅有助于代码管理，还方便使用工具链如 setuptools、pytest、sphinx 等。

下面是一个典型的 Python 项目结构说明，包括 src/、test/、docs/、scripts/ 等目录及其关系。

📁 一、标准项目结构（推荐）

my_project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── module1.py
│       └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── docs/
│   ├── conf.py
│   ├── index.rst
│   └── Makefile
├── scripts/
│   └── setup.sh
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml
├── setup.py (可选)
└── requirements.txt

📁 二、各目录详解

1. src/ —— 源码目录（Source Code）

这是你的核心代码存放的地方，所有模块都应该放在这个目录下的子包中。

• ✅ 优点：
  • 避免将源码直接放在根目录下，避免污染全局命名空间。
  • 更容易控制安装时的包结构。
• ✅ 用法：

  from my_package.module1 import some_function
  

示例结构：

src/
└── my_package/
    ├── __init__.py
    ├── utils.py
    ├── core/
    │   ├── __init__.py
    │   └── engine.py
    └── api/
        ├── __init__.py
        └── server.py

⚠️ 如果你不使用 src/ 目录，也可以把包直接放在根目录下，但不推荐，尤其是用于打包发布时。

2. tests/ —— 测试目录（Unit Tests / Integration Tests）

这是你编写单元测试、集成测试等的地方，一般使用 pytest 或 unittest 来运行。

• ✅ 命名建议：
  • 文件名以 test_ 开头（例如 test_utils.py）。
  • 函数名以 test_ 开头（例如 def test_addition():）。

示例结构：

tests/
├── test_core/
│   ├── test_engine.py
├── test_api/
│   ├── test_server.py
└── conftest.py  # pytest 全局 fixture

3. docs/ —— 文档目录（API Docs, Markdown, etc.）

用于生成和存储项目的文档，通常使用 Sphinx 编写 API 文档。

• ✅ 使用 .rst 格式或 Markdown（配合 myst-parser）。
• ✅ 通过命令 make html 可以生成 HTML 文档。

示例结构：

docs/
├── conf.py
├── index.rst
├── modules.rst
├── images/
│   └── logo.png
└── Makefile

4. scripts/ —— 脚本目录（Build Scripts, CLI Tools）

存放一些辅助脚本，比如构建脚本、环境初始化脚本、CLI 工具等。

示例：

scripts/
├── install_deps.sh
├── build.sh
├── run_dev.sh
└── generate_mock_data.py

5. .gitignore —— Git 忽略配置

告诉 Git 不要提交哪些文件（如缓存、虚拟环境、编译产物等）。

示例内容：

__pycache__
*.pyc
*.log
*.swp
.env
venv/
build/
dist/
*.egg-info/

6. README.md —— 项目简介

Markdown 格式的项目介绍文档，是用户第一眼看到的内容，应包含：

• 项目功能
• 安装方法
• 使用示例
• 贡献指南
• 许可证信息

7. LICENSE —— 授权协议

声明项目的开源许可协议，如 MIT、Apache、GPL 等。

8. pyproject.toml —— 项目元数据和构建配置（推荐）

用于替代旧版的 setup.py，现代 Python 打包推荐使用 pyproject.toml。

示例内容：

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

[project]
name = "my-package"
version = "0.1.0"
description = "A short description of the project."
readme = "README.md"
requires-python = ">=3.8"
license = { file="LICENSE" }
authors = [
    { name="Your Name", email="you@example.com" }
]
dependencies = [
    "requests",
    "numpy",
]

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/my-package"

9. requirements.txt —— 第三方依赖列表

列出项目所需的第三方库，便于快速安装。

示例：

requests==2.28.2
numpy>=1.24.0
pandas

⚠️ 在现代项目中，更推荐使用 pyproject.toml 中的 dependencies 字段来管理依赖。

🧱 三、项目打包与安装流程

1. 构建 wheel 和 sdist

cd my_project/
python -m build

这会生成 dist/ 目录下的 .whl 和 .tar.gz 文件。

2. 安装本地开发版本（editable mode）

pip install -e .

注意：如果你使用了 src/ 结构，这种方式不会污染全局 Python 环境。

🧪 四、测试执行方式（pytest）

确保你在项目根目录下运行测试：

pytest tests/

或者带覆盖率报告：

pytest --cov=my_package tests/

📦 五、常见结构对比

✅ 六、总结：你应该怎么组织自己的项目？

📘 附：参考模板项目（GitHub）

你可以参考这些官方推荐的模板项目结构：

• PyPA sample project
• cookiecutter-pypackage