python-project-guidelines

Python 项目指南

概述

核心原则： 使用 uv 管理环境、尽量减少依赖、采用现代 Python 版本，并为 Web 应用采用异步优先架构来创建 Python 项目。

主要区别： 本指南适用于包含 pyproject.toml 的完整 Python 项目。对于独立的单文件脚本，请改用 standalone-python-scripts 技能。

适用场景

• 启动包含多个模块的新 Python 项目
• 搭建 Python 应用或库的项目骨架
• 使用 pyproject.toml 设置项目结构
• 项目需要多个文件、测试或复杂依赖时

不适用场景：

• 独立的单文件脚本 → 改用 standalone-python-scripts 技能
• 快速实用脚本 → 改用 standalone-python-scripts 技能
• 无需重构且不含 pyproject.toml 的现有项目

独立脚本检查

继续之前： 如果项目是单文件工具或脚本（而非多模块应用），请停止，并改用 standalone-python-scripts 技能。

判断规则：

• 用于独立运行的单个 .py 文件 → standalone-python-scripts
• 多个模块、测试或复杂结构 → 继续使用本指南

使用 uv 管理环境

使用 uv 管理 Python 版本和虚拟环境。

初始化项目

# Initialize new project
uv init myproject
cd myproject

# Specify Python version (see version policy below)
uv init myproject --python 3.12

添加依赖

# Add production dependencies
uv add click arrow sqlalchemy

# Add development dependencies
uv add --dev pytest ruff mypy

# Add with version constraints
uv add 'httpx>=0.24,<0.27'

运行命令

# Run Python scripts
uv run python myscript.py

# Run installed tools
uv run pytest
uv run ruff check .

Python 版本策略

规则： 绝不将已停止维护或距离停止维护不足一年的 Python 版本作为目标版本。

查看当前状态： https://devguide.python.org/versions/

当前安全的最低版本（截至 2026-08-27）： Python 3.11

• 3.10：2026-10 停止维护（不足 1 年）→ 不要作为目标版本
• 3.11：2027-10 停止维护（超过 1 年）→ 可以使用
• 3.12+：可以使用

在 pyproject.toml 中：

[project]
requires-python = ">=3.11"

验证： 设置 requires-python 之前，请查看上方的 devguide URL。如果某个版本将在 12 个月内停止维护，请勿使用。

依赖管理原则

原则： 仅引入完成任务所需的最少外部依赖，以高效完成工作。

判断流程：

1. 标准库能否满足需求？→ 使用标准库
2. 是否有成熟且维护良好的库？→ 使用该库
3. 相比标准库，该依赖是否能带来显著价值？→ 说明理由

示例：

• JSON 解析 → 标准库 json（无需外部依赖）
• HTTP 客户端 → httpx 或 requests（标准库 urllib 使用起来较繁琐）
• 日期/时间 → arrow（参见偏好表）
• CLI 解析 → click（参见偏好表）

库选择偏好

需要外部依赖时，优先选择以下库：

需求	库	备注
参数解析	Click	基于装饰器，API 简洁
日期/时间处理	Arrow	优于标准库 datetime
数据库 ORM	SQLAlchemy	除非绝对必要，否则不要编写原生 SQL
数据库迁移	Alembic	可与 SQLAlchemy 搭配使用
Web（异步）	Quart、FastAPI 或 AioHttp	根据项目需求选择；优先使用异步框架

Web 框架选择：

• FastAPI：适用于带有自动 OpenAPI 文档和类型验证的 API
• Quart：异步版 Flask 替代方案，适合传统 Web 应用
• AioHttp：较底层，适合高性能服务

数据库规则： 使用 SQLAlchemy ORM。仅在以下情况下编写原生 SQL：

• ORM 无法高效表达的复杂查询
• 经测量确认原生 SQL 更快的性能关键路径
• 需要特定 SQL 功能的旧版数据库集成

项目结构

myproject/
├── pyproject.toml
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── main.py
│       └── ...
├── tests/
│   └── ...
└── README.md

主要惯例：

• 包采用 src/ 布局
• 测试与源代码分开存放
• 使用 pyproject.toml 保存所有项目元数据（不要使用 setup.py 或 setup.cfg）

常见错误

错误	正确做法
使用 pip 而不是 uv	始终使用 uv 管理环境
使用 Python 3.10 或更早版本	查看 devguide；使用 3.11+
编写原始 SQL 查询	使用 SQLAlchemy ORM
使用同步 Web 框架（Flask、Django）	使用异步框架（FastAPI、Quart、AioHttp）
使用 argparse 编写 CLI	使用 Click
大量使用标准库 datetime	使用 Arrow
依赖臃肿	审查并移除未使用的包
使用 setup.py	仅使用 pyproject.toml

危险信号——立即停止并检查

• 使用的 Python 版本将在 1 年内结束生命周期
• 编写原始 SQL，而不是使用 SQLAlchemy
• 为新项目使用同步 Web 框架
• 添加依赖却没有合理说明
• 使用 pip/venv 而不是 uv
• pyproject.toml 中缺少 requires-python
• 使用已弃用的打包工具（setup.py、setup.cfg）

验证

完成项目设置前：

1. 检查 Python 版本： uv run python --version → 应为 3.11+
2. 检查依赖： uv tree → 检查是否有不必要的包
3. 验证结构： ls src/ → 应使用 src 布局
4. 测试运行： uv run python -m myproject → 应能无错误执行

参考资料

• Python 版本： https://devguide.python.org/versions/
• Click： https://click.palletsprojects.com/
• Arrow： https://arrow.readthedocs.io/
• SQLAlchemy： https://docs.sqlalchemy.org/
• Alembic： https://alembic.sqlalchemy.org/
• Quart： https://quart.palletsprojects.com/
• FastAPI： https://fastapi.tiangolo.com/
• AioHttp： https://docs.aiohttp.org/
• uv 文档： https://docs.astral.sh/uv/