尊嚴 Python 程式碼撰寫標準技能
生產級 Python 程式碼撰寫標準,旨在撰寫乾淨、可維護、現代化的 Python 程式碼 (版本 3.10-3.13)。
何時使用此技能
當使用者詢問以下問題時自動觸發:
- 「讓這段程式碼更 Pythonic」/「這段 Python 寫得好嗎」
- 「型別提示」/「型別註解」/「typing」
- 「LBYL vs EAFP」/「例外處理」
- 「pathlib vs os.path」/「路徑操作」
- 「CLI 模式」/「click 用法」
- 「程式碼審閱」/「改進這段程式碼」
- 任何 Python 程式碼品質或標準相關問題
注意:此技能為通用 Python 標準,非 Dagster 專屬。Dagster 模式請使用
/dagster-expert。
何時使用此技能 vs. 其他技能
| 使用者需求 | 使用此技能 | 替代技能 |
|---|---|---|
| 「讓這段程式碼更 Pythonic」 | ✅ 是 - Python 標準 | |
| 「這段 Python 寫得好嗎」 | ✅ 是 - 程式碼品質 | |
| 「型別提示」 | ✅ 是 - 型別指引 | |
| 「LBYL vs EAFP」 | ✅ 是 - 例外模式 | |
| 「pathlib vs os.path」 | ✅ 是 - 路徑處理 | |
| 「Dagster 專屬模式」 | ❌ 否 | /dagster-expert |
| 「CLI 參數解析」 | ✅ 是 - CLI 模式 |
核心知識(始終載入)
版本偵測
識別專案的最低 Python 版本,依序檢查:
pyproject.toml- 尋找requires-python欄位(例如requires-python = ">=3.12")setup.py或setup.cfg- 尋找python_requires.python-version檔案 - 包含版本號如3.12或3.12.0- 若未找到版本指定,則預設為 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
參考文件結構
參考文件組織於頂層檔案與子目錄中:
核心參考(與 SKILL.md 同層)
dignified-python-core.md- 基本標準(始終載入)cli-patterns.md- 命令列介面模式(click、argparse)subprocess.md- 子程序操作
版本特定參考(versions/)
versions/python-3.10.md- Python 3.10+ 可用功能versions/python-3.11.md- Python 3.11+ 可用功能versions/python-3.12.md- Python 3.12+ 可用功能versions/python-3.13.md- Python 3.13+ 可用功能
進階主題(references/advanced/)
exception-handling.md- LBYL 模式、錯誤邊界interfaces.md- ABC 與 Protocol 模式typing-advanced.md- 進階型別模式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/api-design.md
閱讀時機:
- 為函式新增預設參數值時
- 定義包含 5 個或更多參數的函式時
- 使用 ThreadPoolExecutor.submit() 時
- 審閱函式簽名時
references/checklists.md
閱讀時機:
- 提交 Python 程式碼前的最終審閱時
- 不確定是否已遵循所有規則時
- 需要快速查閱需求時
如何使用此技能
- 核心知識會自動載入(LBYL、pathlib、基本匯入、反模式)
- 版本偵測會執行一次 - 識別最低 Python 版本並載入對應的版本檔案
- 參考文件會根據上述觸發條件按需載入
- 其他模式可能需要額外載入(CLI 模式、subprocess)
- 每個檔案都是自包含的,提供其領域的完整指引