piglet

piglet

基于 One Python Craftsman 中的模式，为编写和审查 Python 代码提供简明指导。

用途和触发条件

• 用于创建、重构或审查 Python（.py）代码。
• 当代码质量问题涉及命名、控制流、数据处理、错误处理、循环、装饰器、导入、文件 I/O、边界情况或海象运算符时使用。
• 优先考虑清晰度和可维护性。只有在性能确实受限时才进行优化。
• 如果有 $friendly-python，可建议搭配使用，以获取更全面的 Python 风格和审查清单。

决策顺序

1. 正确性和明确的行为
2. 可读性和可维护性
3. 扩展成本和变更隔离
4. 性能和微优化

工作流

1. 在下表中确定主题。
2. 应用指导，并对照 Bad 和 Good 示例。
3. 如果有 $friendly-python，建议将其与此技能配合使用。
4. 重新检查是否引入新的边界情况或可读性退化。

主题

主题	指导	参考
变量和命名	使用描述性名称，避免隐式魔法，尽量缩小变量作用域	references/variables-and-naming.md
分支和条件	避免深层嵌套，将复杂条件封装起来	references/if-else-and-branches.md
数字、字符串和容器	替换魔法字面量，选择合适的容器	references/values-and-containers.md
函数和返回值	保持返回类型稳定，避免错误元组	references/functions-and-returns.md
异常处理	只捕获能够处理的异常，尽量缩小作用域	references/exceptions-handling.md
循环和迭代	优先使用迭代器辅助工具，而非嵌套循环	references/loops-and-iteration.md
装饰器	保留签名，避免装饰器陷阱	references/decorators.md
导入和依赖	通过局部导入和边界设计防止循环依赖	references/imports-and-structure.md
规则和文件 I/O	使用合适的数据结构和 pathlib	references/rules-and-file-io.md
Python 中的 SOLID	确保继承关系可替换，并明确行为	references/solid-python.md
边界情况	在能让主路径更清晰时，优先采用 EAFP	references/edge-cases.md
海象运算符	使用赋值表达式消除重复	references/walrus-operator.md

参考资料

• 每个参考文件都会在其 frontmatter 的 urls 中列出来源 URL。