代码收藏家技术教程 2025-06-14

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/

📦 五、常见结构对比

项目结构	适用场景
单个脚本	小型脚本、一次性任务
没有 `src/` 的简单包	初学者学习、小型库
含 `src/` 的包	正式项目、可发布库
含 `src/` + `tests/` + `docs/`	企业级项目、开源项目

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

用途	推荐结构
写一个小脚本	直接放 `.py` 文件即可
学习或练手的小项目	放在根目录下的包中
正式项目	使用 `src/`、`tests/`、`docs/` 分离结构
发布到 PyPI 的库	使用 `src/` + `pyproject.toml` + `LICENSE` + `README.md`