Pythonic Code Style

任务目标

本 Skill 用于：分析和改进 Python 代码风格，使其更符合 Python 语言特性和最佳实践

能力包含：

• 代码风格分析：识别非 Pythonic 模式，提供改进建议

• Pythonic 惯用法：列表推导、生成器、上下文管理器、装饰器、元类等

• 设计模式应用：SOLID 原则、描述符协议、迭代器协议等

• 性能优化：内存优化、计算优化、I/O 优化、并发模式、缓存策略

• 重构指导：代码异味检测、重构技巧、重构模式、重构流程

• 实战模板：提供可直接使用的代码模板（140+ 个）

触发条件：

• 用户展示代码并请求"如何更 Python 地实现"

• 用户询问"这段代码是否 Pythonic"

• 用户需要代码审查和风格改进建议

• 用户询问 Python 特定语法的最佳实践

• 用户需要性能优化或重构建议

• 用户请求高级 Python 模式或设计模式

核心理念

Friendly Python = User-Friendly + Maintainer-Friendly

┌──────────────────────────────────────────────────────────┐ │ FRIENDLY PYTHON = User-Friendly Python │ ├────────────────────────────────┬─────────────────────────┤ │ User-Friendly │ Maintainer-Friendly │ │ ───────────────── │ ───────────────── │ │ • Sensible defaults │ • Single change point │ │ • Minimal required params │ • Registry over if-else│ │ • Hidden resource mgmt │ • Explicit over magic │ │ • Simple → complex path │ • Readable & debuggable│ └────────────────────────────────┴─────────────────────────┘

设计原则

1. 用户友好 (User-Friendly)

• 默认提供合理值：让快速启动无需阅读文档

• 最少必需参数：隐藏复杂的对象组装

• 透明的资源管理：使用上下文管理器或统一入口

• 简单到复杂：简单路径是默认，复杂需求可显式扩展

2. 维护友好 (Maintainer-Friendly)

• 单点修改：添加新策略/命令/实现时，收敛到一个修改点

• 注册表替代 if-else：使用注册表/插件表替代条件分支链

• 谨慎使用魔法：自动扫描和动态导入需要评估可读性和可调试性

3. 构建模式

• 避免半成品对象：不推荐"实例化后加载"；使用 classmethod 构建

• 多源多入口：env/file/显式使用不同的构建入口，不在 init 用标志

• 减少导入负担：不暴露不必要的命名到包顶层

4. 生态扩展

• 使用扩展点：hook、adapter、auth、middleware

• 避免猴子补丁：改用注册、协议、继承

• 包装而非重写：扩展功能而非覆盖全部

5. 明确性

• 避免 `getattr：优先显式字段和描述符

• 谨慎使用元类：只在必要时使用

• 显式优于隐式：优先可读性而非炫技

操作步骤

┌─────────────────────────────────────────────────────────────┐ │ 1. UNDERSTAND: 理解需求与现有代码 │ ├─────────────────────────────────────────────────────────────┤ │ 2. ANALYZE: 分析代码风格问题，识别非 Pythonic 模式 │ ├─────────────────────────────────────────────────────────────┤ │ 3. IMPROVE: 应用 Pythonic 惯用法和设计模式 │ ├─────────────────────────────────────────────────────────────┤ │ 4. REVIEW: 根据审查清单检查改进方案 │ ├─────────────────────────────────────────────────────────────┤ │ 5. REFINE: 优化细节，提供替代方案和权衡分析 │ └─────────────────────────────────────────────────────────────┘

标准流程：

代码分析

• 阅读用户提供的代码，识别非 Pythonic 的模式

• 参考 references/python-rules.md 中的 Python 之禅和规范

• 关注：命名规范、控制流、数据类型使用、函数设计、异常处理等

Pythonic 改进

• 根据问题类型选择合适的参考文档

• 基础改进：references/control-flow.md、references/data-types.md、references/functions.md

• 高级特性：references/decorators.md、references/advanced-patterns.md

• 性能优化：references/performance-tips.md

• 重构指导：references/refactoring-guide.md

• 应用 Pythonic 惯用法：列表推导、生成器、上下文管理器、装饰器等

• 参考 assets/templates/ 中的标准模板

代码对比与解释

• 展示改进前后的代码对比

• 解释改进的理由和遵循的 Pythonic 原则

• 说明性能、可读性和维护性的提升

• 必要时提供替代方案和权衡分析

最佳实践与进阶建议

• 根据 references/solid-principles.md 提供设计原则建议

• 参考 references/edge-cases.md 处理边界情况

• 提供相关 Pythonic 模式的学习资源和进一步优化方向

可选分支：

• 基础风格问题：使用基础参考文档提供改进建议

• 高级特性应用：推荐使用描述符、元类、迭代器协议等高级模式

• 性能优化需求：结合性能优化参考文档提供建议

• 重构需求：使用重构指南提供系统性改进方案

• 代码已经较好：识别可进一步优化的细节，提供高级优化建议

审查清单

使用此清单进行代码审查或自查：

检查项 问题

🔧 扩展性 新增功能是否只需修改一处代码？

🎯 默认值 API 是否有合理的默认值？是否隐藏了不必要的对象？

📈 复杂度 复杂度是否遵循"简单到复杂"，默认路径是否最轻量？

🔌 扩展点 是否优先使用生态系统的扩展点？

👁️ 明确性 是否为了炫技而牺牲了明确性和可维护性？

🔄 移植代码 移植代码时是否重新设计了调用模式？

推荐与避免的模式

推荐使用的模式

场景 推荐做法

多种实现方式 注册表模式 + 装饰器注册

资源管理 上下文管理器 (with )

多种输入来源 @classmethod 构造器

配置字段 描述符 (Descriptor)

扩展第三方库 官方扩展点 (hook/adapter/auth)

异步操作 async/await + try/except/finally

CLI 工具 argparse + Command 类

复杂对象构建 Builder 模式

策略选择 注册表/字典查找

循环导入 延迟导入/重构模块

避免使用的模式

反模式 问题

大量 if-else 分支 添加功能需要修改多处

init 中使用标志控制路径 互斥参数不明确

getattr 回退 削弱可发现性和类型检查

过度使用元类 污染用户的心智模型

自定义包装回原库 属性重复，维护负担

JS 风格的回调 不 Pythonic

全局状态 难以测试和维护

过度继承 组合优于继承

硬编码配置 缺乏灵活性

裸 except 吞掉所有异常

响应格式

解决代码风格问题时，使用以下格式：

Summary

[完成的工作总结]

Changes Made

Design Decisions

• [为什么选择某些模式]

Review Checklist

• 单点扩展性
• 合理默认值
• 渐进式复杂度
• 正确使用扩展点
• 明确性优于魔法

Suggestions (if any)

• [可以进一步改进的地方]

资源索引

基础参考

• 友好模式：见 references/friendly-patterns.md（Friendly Python 理念、用户友好模式、维护友好模式、构建模式、注册表模式、上下文管理器）

• Python 规则：见 references/python-rules.md（Python 之禅、PEP 8 规范）

• 变量命名：见 references/variables-naming.md（命名原则、布尔变量命名、循环变量命名、临时变量）

• 控制流：见 references/control-flow.md（if-else 优化、卫语句、提前返回、海象运算符、循环优化、match-case）

• 数字和字符串：见 references/data-types.md（数字操作、字符串处理、格式化、正则表达式、类型转换）

• 容器类型：见 references/container-types.md（列表、字典、集合、元组最佳实践、推导式、collections 模块）

• 函数设计：见 references/functions.md（函数设计原则、参数设计、返回值设计、类型提示、高阶函数）

• 异常处理：见 references/exceptions.md（异常处理最佳实践、上下文管理器）

• 装饰器：见 references/decorators.md（装饰器深入应用、类装饰器、参数化装饰器）

• 循环导入：见 references/cyclic-imports.md（循环导入的定义、原因、后果和解决方法）

• 文件操作：见 references/file-operations.md（文件读写、路径处理、pathlib）

进阶参考

• SOLID 原则：见 references/solid-principles.md（面向对象设计原则、设计模式）

• 高级模式：见 references/advanced-patterns.md（元类、描述符、迭代器协议、并发、魔术方法）

• 性能优化：见 references/performance-tips.md（性能分析、内存优化、计算优化、并发、缓存）

• 重构指南：见 references/refactoring-guide.md（代码异味、重构技巧、重构模式、重构工具）

• 边界情况：见 references/edge-cases.md（异常和边界情况处理）

代码模板

• 基础模板：见 assets/templates/naming-patterns.py、assets/templates/control-flow-patterns.py、assets/templates/string-number-operations.py、assets/templates/container-operations.py、assets/templates/exception-handling.py

• 高级模板：见 assets/templates/advanced-patterns.py（元类、描述符、迭代器、装饰器、并发等高级模式）

• 性能模板：见 assets/templates/performance-patterns.py（缓存、批处理、惰性求值、并行处理等性能模式）

核心原则

基于 Python 之禅和 Friendly Python 的核心价值观：

• 优美胜于丑陋：优先选择简洁、优雅的解决方案

• 明了胜于晦涩：代码应该清晰易懂，避免过度设计

• 简洁胜于复杂：用最少的代码完成任务，避免不必要的复杂性

• 复杂胜于凌乱：使用有组织的复杂结构，而非混乱的代码

• 扁平胜于嵌套：减少嵌套层级，提高代码可读性

• 间隔胜于紧凑：合理的空行和空格，让代码更易读

• 可读性很重要：代码是给人读的，清晰度优先

• 实用性胜于纯粹性：考虑实际应用场景和性能需求

• 用户友好 + 维护友好：API 易于使用，代码易于维护

实现方式说明

本 Skill 的所有功能由智能体通过自然语言指导完成，无需脚本执行：

• 代码分析与改进：智能体直接分析代码并提供 Pythonic 改进建议

• 模板推荐：从 assets/templates/ 中选择合适的模板并展示使用方法

• 最佳实践指导：基于参考文档提供详细的指导和示例

使用示例

示例 1：友好模式应用

• 功能说明：应用注册表模式替代 if-else 分支，提高代码可扩展性

• 执行方式：分析现有代码结构，重构为注册表模式

• 参考文档：references/friendly-patterns.md

• 关键要点：

• 识别大量 if-else 分支

• 使用注册表装饰器替代条件链

• 新增功能只需注册，无需修改核心代码

• 保持代码的可读性和可维护性

示例 2：基础循环改进

• 功能说明：将传统的 for 循环转换为列表推导或生成器表达式

• 执行方式：智能体分析代码并提供改进建议

• 参考文档：references/control-flow.md

• 关键要点：

• 识别可转换的循环模式

• 使用列表推导简化代码

• 使用生成器表达式处理大数据

• 保持代码可读性

示例 2：命名规范优化

• 功能说明：改进变量、函数、类的命名

• 执行方式：提供更清晰、更具描述性的命名建议

• 参考文档：references/variables-naming.md

• 模板参考：assets/templates/naming-patterns.py

• 关键要点：

• 使用有意义的名称

• 遵循命名约定（snake_case、CamelCase）

• 避免缩写和歧义

• 使用动词命名函数，名词命名类

示例 3：异常处理改进

• 功能说明：改进异常处理方式和资源管理

• 执行方式：推荐使用更 Python 的异常处理模式

• 参考文档：references/exceptions.md

• 模板参考：assets/templates/exception-handling.py

• 关键要点：

• 捕获特定的异常类型

• 使用上下文管理器管理资源

• 提供有用的错误消息

• 避免裸 except

示例 4：函数设计优化

• 功能说明：优化函数设计和参数传递

• 执行方式：提供函数重写建议

• 参考文档：references/functions.md

• 关键要点：

• 遵循单一职责原则

• 合理使用默认参数和可变参数

• 使用类型提示提高可读性

• 返回一致的结果类型

示例 5：高级模式应用

• 功能说明：应用元类、描述符、迭代器协议等高级模式

• 执行方式：分析需求并推荐合适的高级模式

• 参考文档：references/advanced-patterns.md

• 模板参考：assets/templates/advanced-patterns.py

• 关键要点：

• 理解适用场景和权衡

• 正确实现协议和魔术方法

• 保持代码可读性和可维护性

• 避免过度设计

示例 6：性能优化

• 功能说明：提供性能优化建议

• 执行方式：分析代码并提供优化方案

• 参考文档：references/performance-tips.md

• 模板参考：assets/templates/performance-patterns.py

• 关键要点：

• 使用性能分析工具识别瓶颈

• 选择合适的数据结构和算法

• 使用缓存和批处理

• 考虑并发和异步处理

示例 7：代码重构

• 功能说明：系统性地改进代码结构和质量

• 执行方式：提供重构方案和步骤

• 参考文档：references/refactoring-guide.md

• 关键要点：

• 识别代码异味

• 小步重构，保持测试通过

• 提取方法和类，减少重复

• 简化条件和复杂逻辑

注意事项

• 优先使用 Python 内置功能和标准库，避免重复造轮子

• Pythonic 不等于最简代码，要在简洁和可读性之间平衡

• 遵循 PEP 8 代码风格规范

• 充分利用 Python 的动态特性和语法糖

• 考虑代码的性能和维护性，避免过度优化

• 理解 SOLID 原则，编写可维护的面向对象代码

• 正确处理边界情况和异常

• 高级模式使用时考虑适用场景和可维护性

• 性能优化前先测量，避免过早优化

• 重构时保持测试通过，逐步改进

• 遵循 "用户友好 + 维护友好" 的设计理念

• 使用审查清单确保代码质量

• 优先选择推荐模式，避免反模式