python-dev

Python 開発ルール

概要

コード品質、エラー処理、テスト、環境管理に重点を置いた Python 開発ガイドラインです。Python コードや Jupyter ノートブックを扱う際に適用してください。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• 新しい Python コードを記述する、または既存の Python ファイルを変更する
• Jupyter ノートブックを作成または更新する
• Python 開発環境をセットアップする
• テストを作成または更新する
• Python コードの品質やベストプラクティスを確認する

コード品質

原則

• DRY（同じことを繰り返さない）：コードの重複を避けます
• 継承よりコンポジション：コンポジションパターンを優先します
• 可能な限り純粋関数を使う：副作用のない関数を使用します
• 巧妙な解決策よりシンプルな解決策：読みやすさと保守性を優先します
• 一般的なユースケースを優先して設計する：エッジケースより先に、主要な問題を解決します

スタイルとドキュメント

• 型ヒント必須：すべての関数に型アノテーションを付けます
• snake_case 命名：変数、関数、モジュールには snake_case を使用します
• Google スタイルの docstring：Google スタイルの docstring を使用して、関数、クラス、モジュールを説明します
• 関数を小さく保つ：単一責任の原則に従い、1 つの関数が 1 つの目的を担うようにします
• 既存のコメントを保持する：既存のコードコメントを維持し、必要に応じて更新します

例

def calculate_total(items: list[dict[str, float]], tax_rate: float = 0.08) -> float:
    """Calculate total cost including tax.
    
    Args:
        items: List of items with 'price' key
        tax_rate: Tax rate as decimal (default 0.08)
        
    Returns:
        Total cost including tax
        
    Raises:
        ValueError: If tax_rate is negative or items list is empty
    """
    if not items:
        raise ValueError("Items list cannot be empty")
    if tax_rate < 0:
        raise ValueError("Tax rate cannot be negative")
    
    subtotal = sum(item['price'] for item in items)
    return subtotal * (1 + tax_rate)

エラー処理と効率性

エラー処理

• 具体的な例外型を指定する：裸の except ではなく、具体的な例外を捕捉します
• 入力を早期に検証する：関数の冒頭で入力を確認します
• 裸の except は使用しない：必ず例外型を指定します

効率化のパターン

• f-string：文字列の書式設定には f-string を使用します
• 内包表記：適切な場合は、ループよりリスト／辞書／セット内包表記を優先します
• コンテキストマネージャー：リソース管理には with 文を使用します

例

def process_file(file_path: str) -> list[str]:
    """Process file and return lines.
    
    Args:
        file_path: Path to file
        
    Returns:
        List of non-empty lines
        
    Raises:
        FileNotFoundError: If file doesn't exist
        PermissionError: If file cannot be read
    """
    if not file_path:
        raise ValueError("File path cannot be empty")
    
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            return [line.strip() for line in f if line.strip()]
    except FileNotFoundError:
        raise FileNotFoundError(f"File not found: {file_path}")
    except PermissionError:
        raise PermissionError(f"Permission denied: {file_path}")

テスト（重要）

フレームワークと構成

• pytest のみ：pytest のみを使用します（unittest は使用しません）
• テストの配置場所：すべてのテストを ./tests/ ディレクトリに配置します
• テストパッケージ：tests ディレクトリに __init__.py を含めます
• TDD アプローチ：新規または変更したコードにはすべてテストを作成／更新します
• すべてのテストに合格させる：タスク完了前に、すべてのテストが合格することを確認します

テスト構成の例

project/
├── src/
│   └── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py

テストの例

# tests/test_calculations.py
import pytest
from src.calculations import calculate_total

def test_calculate_total_basic():
    """Test basic total calculation."""
    items = [{'price': 10.0}, {'price': 20.0}]
    result = calculate_total(items, tax_rate=0.1)
    assert result == 33.0

def test_calculate_total_empty_list():
    """Test error handling for empty list."""
    with pytest.raises(ValueError, match="Items list cannot be empty"):
        calculate_total([])

def test_calculate_total_negative_tax():
    """Test error handling for negative tax rate."""
    items = [{'price': 10.0}]
    with pytest.raises(ValueError, match="Tax rate cannot be negative"):
        calculate_total(items, tax_rate=-0.1)

環境管理

依存関係の管理

• uv のみを使用する：パッケージ化、環境管理、スクリプト実行にはすべて uv を使用します
• pip／venv／conda は使用しない：pip、python3 -m venv、conda は使用しません。これらはすべて uv が処理します
• pyproject.toml を信頼できる唯一の情報源とする：すべての依存関係を pyproject.toml に定義します（requirements.txt には定義しません）

環境セットアップの例

# Install dependencies from pyproject.toml
uv sync

# Install with optional dev dependencies
uv sync --extra dev

# Run a script (no activation needed)
uv run python script.py

# Run pytest
uv run pytest

# Add a new dependency
uv add requests

# Remove a dependency
uv remove requests

Python コードの実行

• スクリプトの実行には uv run を使用します。手動で venv を有効化する必要はありません
• 開発ツール（pytest、ruff など）には uv run <tool> を使用します
• 依存関係は pyproject.toml に定義します（requirements.txt には定義しません）

リントとフォーマット（Ruff）

• Ruff：リントとフォーマットの両方に Ruff を使用します（flake8、black、isort の代わり）

# Lint code
uv run ruff check .

# Lint and auto-fix
uv run ruff check --fix .

# Format code
uv run ruff format .

# Check formatting without changes
uv run ruff format --check .

型チェック（Pyright）

# Check types
uv run pyright

注：型チェックには pyright を使用してください。mypy は使用しないでください。

ベストプラクティスのまとめ

1. コード品質：DRY、コンポジション、純粋関数、シンプルな解決策
2. スタイル：型ヒント、snake_case、Google スタイルの docstring、小さな関数
3. エラー：具体的な例外、早期検証、裸の except を使用しない
4. 効率性：f-string、内包表記、コンテキストマネージャー
5. テスト：pytest のみ、TDD、テストは ./tests/ に配置し、すべて合格させる
6. 環境：依存関係と実行には uv のみを使用し、リント／フォーマットには Ruff、型チェックには Pyright を使用する