python-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Conventions

Python 开发约定

Apply these conventions when working on Python files or projects.

在处理 Python 文件或项目时请遵循以下约定。

Dispatch

触发规则

$ARGUMENTS	Action
Active (auto-invoked when working on Python files)	Apply all conventions below
Empty	Display convention summary
`check`	Verify tooling compliance only

$ARGUMENTS	操作
生效（处理 Python 文件时自动触发）	应用以下所有约定
无参数	展示约定摘要
`check`	仅校验工具使用是否符合规范

References

参考文档

File	Purpose
`references/exceptions.md`	When to break conventions (legacy, corporate)

文件	用途
`references/exceptions.md`	可突破约定的场景（遗留项目、企业特定要求）

Tooling

工具使用规范

Package manager:
```
uv
```
for all Python operations (
```
uv run python ...
```
instead of
```
python
```
,
```
uv add
```
instead of
```
pip install
```
)

Project config:

pyproject.toml

with

uv add <pkg>

(never

uv pip install

pip install

)

Type checking:
```
ty
```
(not mypy)
Linting:
```
ruff check
```
and
```
ruff format
```
Testing:
```
uv run pytest
```
Task running:
```
uv run <command>
```
for all script execution

包管理器：所有 Python 操作都使用
```
uv
```
（使用
```
uv run python ...
```
替代
```
python
```
，使用
```
uv add
```
替代
```
pip install
```
）

项目配置：通过

uv add <pkg>

管理

pyproject.toml

（禁止使用

uv pip install

或

pip install

）

类型检查：使用
```
ty
```
（而非 mypy）
代码检查与格式化：使用
```
ruff check
```
和
```
ruff format
```
测试：使用
```
uv run pytest
```
任务运行：所有脚本执行都添加
```
uv run <command>
```
前缀

Virtual Environments

虚拟环境

Let
```
uv
```
manage virtual environments automatically
Never manually create or activate
```
.venv
```
directories
Use
```
uv run
```
to execute within the project environment

交由
```
uv
```
自动管理虚拟环境
禁止手动创建或激活
```
.venv
```
目录
使用
```
uv run
```
在项目环境中执行命令

Preferred Libraries

Purpose	Library	Instead of
Logging	`loguru`	`logging`
Retries	`tenacity`	manual retry loops
Progress bars	`tqdm`	print statements
Web APIs	`fastapi`	flask
CLI tools	`typer`	argparse, click
DB migrations	`alembic`	manual SQL
DB ORM	`sqlmodel`	sqlalchemy raw
UI/demos	`gradio`	streamlit
Numerics	`numpy`	manual math
MCP servers	`fastmcp`	raw MCP protocol

用途	依赖库	替代方案
日志	`loguru`	`logging`
重试	`tenacity`	手动编写重试循环
进度条	`tqdm`	print 语句输出
Web API 开发	`fastapi`	flask
CLI 工具开发	`typer`	argparse、click
数据库迁移	`alembic`	手动编写 SQL
数据库 ORM	`sqlmodel`	原生 sqlalchemy
UI/演示应用	`gradio`	streamlit
数值计算	`numpy`	手动实现数学计算
MCP 服务器开发	`fastmcp`	原生 MCP 协议实现

Project Structure

项目结构

Use
```
pyproject.toml
```
for all project metadata and dependencies
Place source code in a package directory matching the project name
Use
```
uv
```
workspace members for monorepo sub-packages
Run
```
ruff check
```
and
```
ruff format
```
before committing

所有项目元数据和依赖都在
```
pyproject.toml
```
中声明
源代码放在与项目名称同名的包目录下
Monorepo 子包使用
```
uv
```
workspace 成员管理
提交代码前必须执行
```
ruff check
```
和
```
ruff format
```

Critical Rules

核心规则

Always use
```
uv
```
for package management -- never
```
pip install
```
or
```
pip
```
Use
```
uv add
```
to add dependencies -- never
```
uv pip install
```
Use
```
ty
```
for type checking -- never
```
mypy
```
Run
```
uv run pytest
```
before committing any Python changes
Run
```
uv run ruff check
```
to lint before committing
Check
```
references/exceptions.md
```
before breaking any convention
Prefer libraries from the preferred table over their alternatives

Canonical terms (use these exactly):

```
uv
```
-- the required package manager and task runner
```
ty
```
-- the required type checker (not mypy)
```
ruff
```
-- the required linter and formatter
```
pyproject.toml
```
-- the single source of project configuration
```
uv run
```
-- prefix for all Python command execution

包管理必须使用
```
uv
```
，禁止使用
```
pip install
```
或直接调用
```
pip
```
新增依赖必须使用
```
uv add
```
，禁止使用
```
uv pip install
```
类型检查必须使用
```
ty
```
，禁止使用
```
mypy
```
提交任何 Python 代码变更前必须执行
```
uv run pytest
```
提交前必须执行
```
uv run ruff check
```
做代码检查
若要突破任何约定，请先查阅
```
references/exceptions.md
```
优先选用推荐列表中的库，而非其他替代方案

规范术语（请严格按照以下表述使用）：

```
uv
```
-- 要求使用的包管理器和任务运行器
```
ty
```
-- 要求使用的类型检查器（而非 mypy）
```
ruff
```
-- 要求使用的代码检查器和格式化工具
```
pyproject.toml
```
-- 项目配置的唯一可信源
```
uv run
```
-- 所有 Python 命令执行的前缀