name: python-engineering description: Python 工程化開發規範：虛擬環境隔離、標準專案結構、依賴鎖定、pytest 單元測試、ruff 程式碼檢查與打包釋出流程。在建立 Python 專案、管理環境與依賴、編寫執行測試、構建釋出程式碼時使用。 when_to_use: 需要建立規範的 Python 專案、管理虛擬環境與依賴、編寫和執行單元測試、打包釋出程式碼時應用

Python 工程化開發規範

面向 Windows PowerShell 環境（用分號串聯命令，不用 &&）。目標是讓每個 Python 專案環境隔離、結構標準、可測試、可釋出。

1. 環境管理

• 每個專案必須使用獨立虛擬環境，禁止向全域性直譯器安裝專案依賴。
• 建立：python -m venv .venv；啟用（PowerShell）：.venv\Scripts\Activate.ps1；之後一律用 python/pip（指向環境內直譯器）。
• 若執行策略阻止啟用指令碼，改用 python -m pytest、python -m ruff 等 -m 模組方式執行，效果等價。
• .venv/ 必須寫入 .gitignore。
• 直譯器版本確認：python --version。Windows 下控制台輸出編碼問題時設定 $env:PYTHONIOENCODING="utf-8"，檔案一律以 UTF-8 讀寫。

2. 專案結構

採用 src 佈局：

專案名/
├── .venv/
├── src/
│   └── 包名/
│       └── __init__.py
├── tests/
│   └── test_*.py
├── pyproject.toml
├── .gitignore
└── README.md

• 原始碼放 src/包名/，測試放 tests/，測試檔案以 test_ 開頭。
• pyproject.toml 作為唯一專案後設資料與工具配置入口：

  7w4.net小蔥技能站收錄全網優質技能，值得收藏。

[project]
name = "包名"
version = "0.1.0"
description = "一句話描述"
requires-python = ">=3.9"

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["src"]

[tool.ruff]
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

• .gitignore 至少包含：.venv/、__pycache__/、*.pyc、dist/、build/、*.egg-info/。

3. 依賴管理

• 安裝依賴後立刻匯出鎖定檔案：python -m pip freeze > requirements.lock.txt。
• 執行依賴與開發依賴分開：執行依賴寫入 pyproject.toml 的 dependencies，開發工具（pytest、ruff）放 requirements-dev.txt。
• 安裝鎖定環境：python -m pip install -r requirements.lock.txt。
• 禁止憑記憶補寫依賴版本，以 pip freeze 實際輸出為準。

4. 單元測試

• 測試框架統一用 pytest，測試檔案放 tests/，函式命名 test_行為描述。
• 執行：python -m pytest -q；只跑單檔案：python -m pytest tests/test_xxx.py -q。
• 交付前必須全量跑一遍且全部通過，失敗先定位根因再修，不得刪測試或加 skip 繞過。
• 純邏輯模組優先寫無副作用的單元測試；涉及外部資源的用 pytest 的 fixture 隔離。

5. 程式碼質量

• 統一用 ruff 做檢查與格式化：python -m ruff check . --fix，再 python -m ruff format .。
• 交付前對改動過的原始碼目錄跑一遍，問題清零後才算完成。
• 行寬以 pyproject.toml 中 line-length = 100 為準。

6. 打包釋出

• 版本號遵循語義化版本 主.次.修訂，寫在 pyproject.toml 的 [project].version，釋出前更新。
• 構建前先清理舊產物：刪除 dist/、build/、*.egg-info/。
• 構建：python -m pip install build，然後 python -m build，產物在 dist/。
• 本地驗證：新建一個乾淨虛擬環境安裝產物包，import 並呼叫核心功能確認可用。
• 僅在使用者明確要求時才執行上傳到包倉庫的操作，上傳前先確認目標倉庫。

工作流摘要

新專案從零開始按此順序：建立 venv → 建目錄與 pyproject.toml → 寫原始碼 → ruff 檢查格式化 → 寫測試並跑通 → 匯出 requirements.lock.txt。交付結論只以測試全通過和實際執行為準。

質量中上等，內容覆蓋全面且實用。對於需要規範化開發流程的 Python 開發者來說很有參考價值。優點是結構清晰、命令具體、配置示例完整；不足是純理論指導缺少實踐示例，初次使用時需要花費較多時間理解消化。普通使用者如果只是偶爾寫 Python 指令碼，可能不會用到這麼全面的規範。