開發工具

熟悉下列開發工具，有助於理解如何開發及除錯 Osprey。

Ruff

Ruff 負責 linting 與 formatting，取代 Black、isort、Flake8 等工具。設定位於 pyproject.toml 的 [tool.ruff]。啟用的 Rules 包括 pycodestyle errors E、pyflakes F、import sorting I，以及 flake8-bugbear 的 mutable default arguments 檢查 B006。

Commands 如下。

# Check for issues
uv run ruff check

# Fix auto-fixable issues
uv run ruff check --fix

# Format code
uv run ruff format

# Check specific files
uv run ruff check path/to/file.py

MyPy

MyPy 負責 Python static type checking。pyproject.toml 中的 [tool.mypy] 設定會載入 Pydantic 與 SQLAlchemy Plugins，放寬 strict mode 以配合 codebase 中較舊的部分，並跳過 generated protobuf files。

Commands 如下。

# Type check entire project
uv run mypy .

# Type check specific files
uv run mypy path/to/file.py

# Type check entire module
uv run mypy osprey_worker/

# Check with verbose output
uv run mypy --show-traceback path/to/file.py

Pre-commit

Pre-commit 提供在 commit 程式碼前執行自動品質檢查的 Git hooks，設定位於 .pre-commit-config.yaml。

Commands 如下。

# Run all hooks on staged files
uv run pre-commit run

# Run all hooks on all files
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run ruff

# Update hook versions
uv run pre-commit autoupdate

# Bypass hooks (emergency only)
git commit --no-verify

git commit --no-verify 只適合已理解並記錄檢查失敗原因的緊急情況，不應用來略過需要修正的品質或安全問題。pre-commit autoupdate 會變更工具版本，執行及提交前須依 Osprey 的 dependency approval 規則取得維護者同意。

UV

UV 負責 Python packages 與 environments 管理，主要 commands 如下。

# Install dependencies
uv sync

# Add new dependency
uv add package-name

# Add development dependency
uv add --group dev package-name

# Remove dependency
uv remove package-name

# Run command in environment
uv run command-name

# Update dependencies
uv lock --upgrade

新增、移除或升級 dependency 會改變專案供應鏈與 lockfile。依 Osprey 規則，執行 uv add、uv remove 或 uv lock --upgrade 前，須取得維護者對 dependency 與授權相容性的明確同意。