dignified-python

得体的 Python

关于编写整洁、易维护、现代 Python 代码（版本 3.10-3.13）的鲜明风格指南。

何时使用此技能

当用户询问以下内容时自动调用：

• “让这段代码更符合 Python 风格”／“这算是好的 Python 代码吗”
• “类型提示”／“类型注解”／“typing”
• “LBYL 还是 EAFP”／“异常处理”
• “pathlib 还是 os.path”／“路径操作”
• “CLI 模式”／“click 用法”
• “代码审查”／“改进这段代码”
• 任何关于 Python 代码质量或规范的问题

注意：此技能提供的是通用 Python 风格指南，并非 Dagster 专用。它体现了一套明确、偏向 LBYL 的约定；必要时，项目约定可以覆盖这些约定。

何时使用此技能，而非其他技能

用户需求	使用此技能	替代技能
“让这段代码更符合 Python 风格”	✅ 是 - Python 规范
“这算是好的 Python 代码吗”	✅ 是 - 代码质量
“类型提示”	✅ 是 - typing 指南
“LBYL 还是 EAFP”	✅ 是 - 异常模式
“pathlib 还是 os.path”	✅ 是 - 路径处理
“Dagster 最佳实践”	❌ 否	/dagster-best-practices
“实现 X 流水线”	❌ 否	使用 /dg 进行实现
“应该使用哪种集成”	❌ 否	/dagster-expert
“CLI 参数解析”	✅ 是 - CLI 模式

核心知识（始终加载）

@dignified-python-core.md

版本检测

通过以下方式（按顺序）确定项目的最低 Python 版本：

1. pyproject.toml - 查找 requires-python 字段（例如，requires-python = ">=3.12"）
2. setup.py 或 setup.cfg - 查找 python_requires
3. .python-version 文件 - 包含类似 3.12 或 3.12.0 的版本
4. 如果未找到版本说明，则默认为 Python 3.12

确定版本后，加载相应的特定版本文件：

• Python 3.10：加载 versions/python-3.10.md
• Python 3.11：加载 versions/python-3.11.md
• Python 3.12：加载 versions/python-3.12.md
• Python 3.13：加载 versions/python-3.13.md

条件加载（根据任务模式加载）

上述核心文件涵盖了 80% 以上的 Python 代码模式。仅在检测到特定模式时，才加载以下附加文件：

模式检测示例：

• 如果任务提到“click”或“CLI” -> 加载 cli-patterns.md
• 如果任务提到“subprocess” -> 加载 subprocess.md

参考文档结构

此技能的参考资料按主题组织：

核心参考资料

• dignified-python-core.md - 基本规范（始终加载）
• cli-patterns.md - 命令行界面模式（click、argparse）

特定版本参考资料（versions/）

• python-3.10.md - Python 3.10 及更高版本提供的功能
• python-3.11.md - Python 3.11 及更高版本提供的功能
• python-3.12.md - Python 3.12 及更高版本提供的功能
• python-3.13.md - Python 3.13 及更高版本提供的功能

高级主题（references/advanced/）

• exception-handling.md - LBYL 模式、错误边界
• interfaces.md - ABC 和 Protocol 模式
• typing-advanced.md - 高级 typing 模式
• api-design.md - API 设计原则

何时阅读各参考文档

references/advanced/exception-handling.md

在以下情况下阅读：

• 编写 try/except 代码块
• 封装可能引发异常的第三方 API
• 看到或编写 from e 或 from None
• 不确定是否存在 LBYL 替代方案

references/advanced/interfaces.md

在以下情况下阅读：

• 创建 ABC 或 Protocol 类
• 编写 @abstractmethod 装饰器
• 设计网关层接口
• 在 ABC 和 Protocol 之间进行选择

references/advanced/typing-advanced.md

在以下情况下阅读：

• 使用 typing.cast()
• 创建 Literal 类型别名
• 在条件代码块中收窄类型

references/module-design.md

在以下情况下阅读：

• 创建新的 Python 模块
• 添加模块级代码（简单常量除外）
• 在模块级使用 @cache 装饰器
• 在模块级看到 Path() 或计算操作
• 考虑使用内联导入

references/advanced/api-design.md

在以下情况下阅读：

• 为函数添加默认参数值
• 定义参数数量达到 5 个或更多的函数
• 使用 ThreadPoolExecutor.submit()
• 审查函数签名

references/checklists.md

在以下情况下阅读：

• 提交 Python 代码前进行最终审查
• 不确定是否遵循了所有规则
• 需要快速查阅要求

如何使用此技能

1. 核心知识会自动加载（默认值、pathlib、导入、反模式）
2. 版本检测只进行一次——确定最低 Python 版本并加载相应的版本文件
3. 参考文档会根据上述触发条件按需加载
4. 其他模式可能需要额外加载（CLI 模式、子进程）
5. 每个文件都是独立的，包含其所属领域的完整指南