26.1 引言

随着项目规模增长，良好的项目结构和规范对于代码的可维护性、可读性、可扩展性至关重大。
本章将学习：

• Python 项目推荐目录结构
• 虚拟环境与依赖管理
• 代码风格规范（PEP8）
• 类型注解与静态检查
• 文档与版本管理

26.2 推荐的项目目录结构

标准项目结构示例：

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── main.py
│       └── utils.py
├── tests/
│   └── test_utils.py
├── docs/
│   └── index.md
├── requirements.txt
├── pyproject.toml
├── README.md
├── .gitignore
└── setup.cfg / setup.py

优势：

• src/ 结构避免测试误导导入
• 清晰区分源代码、测试、文档
• 方便自动化工具（pytest、mypy、sphinx等）识别

26.3 虚拟环境与依赖管理

26.3.1 使用 venv

示例：

python -m venv venv
source venv/bin/activate   # macOS/Linux
venvScriptsactivate      # Windows

pip install -r requirements.txt

每个项目独立虚拟环境，避免依赖冲突。

26.3.2 使用 pip-tools 管理依赖

示例：

pip install pip-tools

生成锁定依赖：

echo "requests" > requirements.in
pip-compile requirements.in
pip install -r requirements.txt

✅ requirements.in 只列主依赖，requirements.txt 锁版本号。

26.4 代码风格规范（PEP8）

26.4.1 基本规范

• 缩进使用 4个空格
• 每行最多 79 个字符
• 变量名用 小写+下划线
• 类名用 驼峰命名法
• 顶层定义之间空两行

示例：

class MyClass:
    def do_something(self):
        print("hello")

26.4.2 使用 flake8 检查

pip install flake8
flake8 src/

✅ 自动检查 PEP8 风格问题。

26.5 类型注解与静态检查

示例：

def add(a: int, b: int) -> int:
    return a + b

使用 mypy 静态检查：

pip install mypy
mypy src/

✅ 提前发现类型错误，提升代码可维护性。

26.6 文档与版本管理

• 在 README.md 中说明项目简介、安装方式、用法示例
• 使用 docs/ 目录编写详细文档，可配合 sphinx 生成 API 文档
• 使用 git 和 git tag 管理版本号
• 在 pyproject.toml 或 setup.cfg 中维护版本信息

pyproject.toml 示例：

[project]
name = "myproject"
version = "0.1.0"
description = "My awesome Python project"

26.7 小结

✅ 本章内容能协助你从零搭建一个规范、专业、可维护的 Python 项目结构。