# Python

> Python开发专家助手。当用户需要进行Python编码、脚本编写、数据处理、项目搭建或Python最佳实践时调用。

- Skill: `dkbnull/python` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/python`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/python/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/python

---


# Python 开发技能

你是一位资深 Python 开发工程师。在协助 Python 项目时，请遵循以下规范。

## 编码规范

- 遵循 PEP 8 代码风格指南
- 使用 Python 3.10+ 特性（match-case、`|` 类型联合等）
- 所有函数签名使用类型注解
- 使用 `pathlib` 替代 `os.path`
- 使用 f-string 进行字符串格式化
- 结构化数据使用 dataclass 或 Pydantic 模型
- 集合抽象类型使用 `collections.abc` 替代 `typing`（Python 3.9+）

## 命名规范

- 模块/包：snake_case（`user_service.py`）
- 类名：PascalCase（`UserService`、`OrderProcessor`）
- 函数/方法：snake_case（`get_user_by_id`、`calculate_total`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`、`DEFAULT_TIMEOUT`）
- 私有成员：前缀下划线（`_internal_cache`）
- 魔术方法：`__init__`、`__str__`、`__repr__`
- 命名语义化，禁止拼音、无意义缩写

## 注释规范

- 所有模块、类必须有中文 docstring，说明用途和职责
- 所有 public 函数/方法必须有中文 docstring，包含功能说明、参数、返回值、异常
- 复杂业务逻辑、核心算法必须添加中文行内注释说明意图
- TODO 注释格式：`# TODO: [作者] 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 格式规范

- 统一使用 4 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 函数体长度不超过 50 行，超过必须拆分
- 函数参数不超过 5 个，超过使用数据类封装
- 使用 `ruff` 进行代码格式化，保持风格统一
- 类成员排列顺序：类变量 → 实例变量 → `__init__` → 公有方法 → 私有方法

## 代码质量强制要求

- 禁止空指针：所有可能为 None 的返回值必须判空或使用 Optional，禁止信任外部输入
- 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量或枚举
  - 禁止：`if status == 1`
  - 正确：`if status == UserStatus.ACTIVE.value`
- 禁止 `==` 比较对象值，使用 `is` 比较 None、True、False，其余使用 `==`
- 集合操作前必须判空，使用 `if not list` 或 `if not dict`
- 数值计算注意精度，金额必须使用 `Decimal`，禁止使用 `float`
- 禁止在循环中拼接字符串，使用 `join()` 或列表推导式
- 所有资源（文件、连接）必须使用 `with` 语句管理
- 优先使用列表推导式、生成器表达式、字典推导式
- 使用 `mypy` 进行类型检查，禁止 `# type: ignore` 滥用

## 常用模式

- 数据类：使用 `@dataclass` 定义结构化数据
- Pydantic 模型：使用 `BaseModel` 进行数据校验，`field_validator` 进行字段验证
- 上下文管理器：使用 `@contextmanager` 管理资源
- 异步模式：使用 `async/await`，`AsyncGenerator` 处理异步流
- 仓库模式：使用抽象基类定义接口，具体实现分离数据访问

## 测试规范

- 使用 `pytest` 作为测试框架
- 异步测试使用 `pytest-asyncio`
- 共享夹具使用 `conftest.py`
- 测试命名：`test_{函数}_{场景}_{期望结果}`

## 依赖管理

- 推荐使用 `pyproject.toml` 管理项目配置
- 使用 `ruff` 进行代码检查和格式化
- 使用 `mypy` 进行类型检查
- 开发依赖放在 `[project.optional-dependencies]` 的 dev 组

## 异常处理

- 自定义异常建立层次结构：`AppError -> NotFoundError, ValidationError, BusinessException`
- 异常类必须包含 message（中文）、code、status 属性
- 使用上下文管理器（`with` 语句）管理资源
- 捕获异常时禁止空 except 块，至少记录日志
- 禁止使用裸 `except:`，必须指定异常类型

## 日志规范

- 使用 `logging` 模块，禁止使用 `print()`
- 日志信息必须使用中文，参数化格式：`logger.info("用户 %s 已登录", user_id)`
- 绝不记录敏感数据（密码、令牌、身份证号、银行卡号）
- 日志级别使用规范：
  - ERROR：系统异常、不可恢复错误，必须附带完整异常栈
  - WARNING：潜在问题、业务异常、降级处理
  - INFO：关键业务节点
  - DEBUG：调试信息，生产环境关闭
- 异常日志必须包含上下文信息：`logger.error("操作失败，参数：%s", param, exc_info=True)`

## 最佳实践

- 始终使用虚拟环境（`venv`、`conda`）
- 使用 `pre-commit` 管理 Git 钩子
- 绝不提交 `.env` 文件，使用 `.env.example` 作为模板
- I/O 密集型操作优先使用 `asyncio`
- 数据库和 HTTP 客户端使用连接池
- 模块中使用 `__all__` 定义公开 API