Python编码规范

技能简介

Python技能提供编码指南和最佳实践，涵盖PEP 8风格规范、语法验证、单元测试执行、依赖管理等内容，帮助开发者编写符合现代Python标准的代码。

业务背景

开发团队编写Python代码时，常因风格不统一导致代码难维护、协作效率低。该技能提供PEP 8规范指导、语法自动检查、单元测试执行及依赖管理，帮助团队建立统一的编码标准，减少低级错误，提升代码质量和可维护性，让新人更快融入项目。

落地案例：某数据分析团队多人协作开发项目，成员编码习惯各异。启用该技能后，代码提交前自动检查PEP 8风格和语法问题，统一使用uv管理依赖避免版本冲突，运行单元测试确保功能正确。团队代码风格趋于一致，Code Review时间缩短，后期维护成本明显降低。

能做什么

• 规范Python代码风格(PEP 8)
• 验证代码语法正确性
• 执行单元测试
• 管理项目依赖(uv/pip)
• 应用Pythonic编程模式
• 识别和避免常见反模式

使用说明

1. 安装技能

clawhub install python

2. 提交前检查清单

语法检查(必需)：

python -m py_compile *.py

运行测试：

python -m pytest tests/ -v 2>/dev/null || python -m unittest discover -v 2>/dev/null || echo "No tests found"

格式检查(如有工具)：

ruff check . --fix 2>/dev/null || python -m black --check . 2>/dev/null

3. 代码风格规范

• 缩进：4个空格，不使用tab
• 行长度：88字符(Black默认)或79字符(严格PEP 8)
• 顶级定义前空两行，类内方法间空一行
• 导入顺序：标准库 → 第三方 → 本地，每组内按字母排序
• 命名：函数/变量用snake_case，类用PascalCase，常量用UPPER_CASE

4. Python版本要求

• 最低版本：Python 3.10+(3.9将于2025年10月停止维护)
• 推荐版本：Python 3.11-3.13用于新项目
• 禁止使用Python 2语法

5. 依赖管理

优先使用uv，回退到pip：

if command -v uv &>/dev/null; then
    uv pip install 
    uv pip compile requirements.in -o requirements.txt
else
    pip install 
fi

新项目使用uv初始化：

uv init
# 或
uv venv && source .venv/bin/activate

6. Pythonic模式推荐

使用推导式替代循环：

squares = [x**2 for x in range(10)]
lookup = {item.id: item for item in items}

使用上下文管理器：

with open("file.txt") as f:
    data = f.read()

使用f-string格式化：

msg = f"Hello {name}, you have {count} items"

使用pathlib处理路径：

from pathlib import Path
config = Path.home() / ".config" / "app.json"

7. 避免的反模式

• 不要使用可变默认参数：def bad(items=[])
• 不要使用裸except：except:，应使用except Exception:
• 避免全局状态
• 避免from module import *
• 字符串拼接使用join而非循环
• 使用is None而非== None

输入与输出

见下方输入与输出表格。

项目	内容
输入	Python代码文件、测试文件、依赖需求
输出	语法检查结果、格式化后代码、测试报告、依赖锁定文件
适用人群	Python开发者、代码审查者、技术团队
不包含	自动修复所有问题、集成到CI/CD、其他语言支持

 

风险提示

• 代码规范检查工具需要单独安装(ruff/black)
• Python版本要求较新，旧项目可能需升级
• uv工具较新，稳定性可能不如pip
• 格式化工具可能改变代码风格，提交前需 review

来源信息

原始链接：GitHub

来源类型：github