Python コードスタイル & ドキュメンテーション

一貫性のあるコードスタイルと明確なドキュメンテーションにより、コードベースは保守性が高く、協調的になります。このスキルは、最新の Python ツーリング、命名規則、ドキュメンテーション標準をカバーしています。

このスキルを使う場合

• 新しいプロジェクトのリント設定とフォーマット設定
• ドキュメント文字列の執筆またはレビュー
• チーム開発基準の確立
• ruff、mypy、または pyright の設定
• スタイルの一貫性に関するコード審査
• プロジェクトドキュメントの作成

主要な概念

1. 自動フォーマット

フォーマットの議論はツールに任せましょう。一度設定すれば、自動的に適用されます。

2. 一貫性のある命名

PEP 8 規則に従い、意味のある説明的な名前を使用します。

3. コードとしてのドキュメンテーション

ドキュメント文字列は、説明するコードと同じ場所で管理する必要があります。

4. 型アノテーション

最新の Python コードは、すべてのパブリック API に型ヒントを含める必要があります。

クイックスタート

# 最新のツーリングをインストール
pip install ruff mypy

# pyproject.toml で設定
[tool.ruff]
line-length = 120
target-version = "py312"  # プロジェクトの最小 Python バージョンに応じて調整

[tool.mypy]
strict = true

基本的なパターン

パターン 1: 最新の Python ツーリング

ruff をオールインワンのリンターおよびフォーマッターとして使用します。flake8、isort、black を単一の高速ツールに置き換えます。

# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"  # プロジェクトの最小 Python バージョンに応じて調整

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort
    "B",    # flake8-bugbear
    "C4",   # flake8-comprehensions
    "UP",   # pyupgrade
    "SIM",  # flake8-simplify
]
ignore = ["E501"]  # 行の長さはフォーマッターで処理

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

実行方法:

ruff check --fix .  # リント実行と自動修正
ruff format .       # コードのフォーマット

パターン 2: 型チェック設定

本番環境コード用に厳密な型チェックを設定します。

# pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

代替案: pyright を使用してより高速なチェックを行います。

[tool.pyright]
pythonVersion = "3.12"
typeCheckingMode = "strict"

パターン 3: 命名規則

PEP 8 に従い、簡潔性より明確性を重視します。

ファイルとモジュール:

# 良い例: 説明的な snake_case
user_repository.py
order_processing.py
http_client.py

# 避けるべき: 省略形
usr_repo.py
ord_proc.py
http_cli.py

クラスと関数:

# クラス: PascalCase
class UserRepository:
    pass

class HTTPClientFactory:  # アクロニムは大文字のまま
    pass

# 関数と変数: snake_case
def get_user_by_email(email: str) -> User | None:
    retry_count = 3
    max_connections = 100

定数:

# モジュールレベルの定数: SCREAMING_SNAKE_CASE
MAX_RETRY_ATTEMPTS = 3
DEFAULT_TIMEOUT_SECONDS = 30
API_BASE_URL = "https://api.example.com"

パターン 4: インポート構成

インポートを一貫した順序でグループ化: 標準ライブラリ、サードパーティ、ローカル。

# 標準ライブラリ
import os
from collections.abc import Callable
from typing import Any

# サードパーティパッケージ
import httpx
from pydantic import BaseModel
from sqlalchemy import Column

# ローカルインポート
from myproject.models import User
from myproject.services import UserService

絶対インポートのみを使用します:

# 推奨
from myproject.utils import retry_decorator

# 相対インポートは避ける
from ..utils import retry_decorator

応用的なパターン

パターン 5: Google スタイルのドキュメント文字列

すべてのパブリッククラス、メソッド、関数に対してドキュメント文字列を記述します。

シンプルな関数:

def get_user(user_id: str) -> User:
    """ユーザーを一意の識別子で取得します。"""
    ...

複雑な関数:

def process_batch(
    items: list[Item],
    max_workers: int = 4,
    on_progress: Callable[[int, int], None] | None = None,
) -> BatchResult:
    """ワーカープールを使用してアイテムを並行処理します。

    設定されたワーカー数を使用してバッチ内の各アイテムを処理します。
    進捗状況はオプションのコールバックで監視できます。

    Args:
        items: 処理するアイテム。空にすることはできません。
        max_workers: 最大並行ワーカー数。デフォルトは 4。
        on_progress: オプション。(完了数, 合計数) を受け取るコールバック。

    Returns:
        成功したアイテムと、関連する例外を含む任意の失敗を含む
        BatchResult。

    Raises:
        ValueError: items が空の場合。
        ProcessingError: バッチを処理できない場合。

    Example:
        >>> result = process_batch(items, max_workers=8)
        >>> print(f"Processed {len(result.succeeded)} items")
    """
    ...

クラスドキュメント文字列:

class UserService:
    """ユーザー操作を管理するサービス。

    ユーザーの作成、取得、更新、削除のメソッドを提供します。
    適切な検証とエラーハンドリングを含みます。

    Attributes:
        repository: ユーザー永続化用のデータアクセスレイヤー。
        logger: 操作追跡用のロガーインスタンス。

    Example:
        >>> service = UserService(repository, logger)
        >>> user = service.create_user(CreateUserInput(...))
    """

    def __init__(self, repository: UserRepository, logger: Logger) -> None:
        """ユーザーサービスを初期化します。

        Args:
            repository: ユーザー用のデータアクセスレイヤー。
            logger: 操作追跡用のロガー。
        """
        self.repository = repository
        self.logger = logger

パターン 6: 行の長さとフォーマット

最新のディスプレイ対応で行長を 120 文字に設定しながら可読性を保ちます。

# 良い例: 読みやすい改行
def create_user(
    email: str,
    name: str,
    role: UserRole = UserRole.MEMBER,
    notify: bool = True,
) -> User:
    ...

# 良い例: メソッドチェーンを明確に
result = (
    db.query(User)
    .filter(User.active == True)
    .order_by(User.created_at.desc())
    .limit(10)
    .all()
)

# 良い例: 長い文字列をフォーマット
error_message = (
    f"Failed to process user {user_id}: "
    f"received status {response.status_code} "
    f"with body {response.text[:100]}"
)

パターン 7: プロジェクトドキュメンテーション

README 構成:

# プロジェクト名

プロジェクトの説明。

## インストール

\`\`\`bash
pip install myproject
\`\`\`

## クイックスタート

\`\`\`python
from myproject import Client

client = Client(api_key="...")
result = client.process(data)
\`\`\`

## 設定

環境変数と設定オプションをドキュメント化します。

## 開発

\`\`\`bash
pip install -e ".[dev]"
pytest
\`\`\`

CHANGELOG フォーマット (Keep a Changelog):

# Changelog

## [Unreleased]

### Added
- 新機能 X

### Changed
- Y の動作を変更

### Fixed
- Z のバグ修正

ベストプラクティスの要約

1. ruff を使用 - リントとフォーマット用の単一ツール
2. 厳密な mypy を有効化 - ランタイム前に型エラーをキャッチ
3. 120 文字行 - 可読性の現代的な標準
4. 説明的な名前 - 簡潔性より明確性
5. 絶対インポート - 相対インポートより保守しやすい
6. Google スタイルのドキュメント文字列 - 一貫した読みやすいドキュメンテーション
7. パブリック API をドキュメント化 - すべてのパブリック関数にドキュメント文字列が必要
8. ドキュメントを最新に保つ - ドキュメンテーションをコードとして扱う
9. CI で自動化 - すべてのコミットでリンターを実行
10. Python 3.10+ をターゲット - 新しいプロジェクトの場合は、最新言語機能のために Python 3.12+ が推奨されます