coding-standards

Python コーディング標準

Python コーディング標準とベストプラクティスを包括的にまとめています。AI エージェントや LLM が、高品質で高性能、かつ保守しやすい Python コードを生成できるよう設計されています。

カテゴリー

エラー処理 [CRITICAL]

失敗が隠されたり、成功したかのように報告されたりするのを防ぎます。

ルール	説明
error-no-silent-exceptions	例外を握りつぶさない

パフォーマンス最適化 [CRITICAL]

Python の最適化パターンを適用して、処理速度とメモリ効率を向上させます。

ルール	説明
perf-list-comprehension	ループよりリスト内包表記を優先する（1.5～2 倍高速）
perf-generator-expression	大規模なデータセットにはジェネレーターを使用する（メモリ使用量 O(1)）
perf-dict-get	効率的にデフォルト値を取得するには dict.get() を使用する
perf-set-lookup	高速な検索には set を使用する（O(n) に対して O(1)）
perf-str-join	文字列の連結には join を使用する（O(n²) に対して O(n)）

非同期処理 [HIGH]

asyncio を使用した効率的な非同期プログラミングのパターンです。

ルール	説明
async-gather	独立したタスクには asyncio.gather を使用する
async-create-task	バックグラウンドタスクを適切に作成する
async-context-manager	async with でリソースを管理する
async-semaphore	セマフォで同時実行数を制限する

設計原則 [HIGH]

保守性と拡張性を高めるソフトウェア設計原則です。

ルール	説明
design-philosophy	DRY、YAGNI、KISS の原則
design-single-responsibility	単一責任の原則
design-dependency-injection	依存性注入による疎結合
design-no-global-singleton	グローバルなシングルトンやモジュールレベルの共有インスタンスを避ける
solid-ocp	オープン・クローズドの原則
solid-lsp	リスコフの置換原則
solid-isp	インターフェース分離の原則
design-pure-functions	副作用のない純粋関数を優先する
design-early-return	早期リターンでネストを減らす

ドキュメント [HIGH]

公開 API の明確さと、機械で検証可能な契約のためのドキュメント標準です。

ルール	説明
doc-docstring	Google スタイルの docstring で公開 API を文書化する
doc-type-hints	公開 API に型ヒントを必須とする

データ検証 [HIGH]

信頼境界を越えるデータの検証パターンです。

ルール	説明
validation-pydantic	境界データの検証に Pydantic を使用する

オブジェクト指向プログラミング [MEDIUM]

Python らしいオブジェクト指向プログラミングのベストプラクティスです。

ルール	説明
oop-composition-over-inheritance	継承よりコンポジションを優先する
oop-dataclass	データコンテナーには dataclass を使用する
oop-protocol	抽象基底クラスより Protocol を優先する
oop-property	getter の代わりに property を使用する

クイックリファレンス

エラー処理

try:
    config = parse_config(path)
except ConfigParseError as exc:
    raise StartupError(f"Invalid configuration: {path}") from exc


def main() -> int:
    try:
        start_application()
    except StartupError:
        logger.exception("Application startup failed")
        return 1  # explicit non-success outcome at the process boundary
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

パフォーマンスパターン

# List comprehension (not loops)
result = [x * 2 for x in items]

# Generator for large data
total = sum(x * x for x in range(1_000_000))

# dict.get() with default
value = config.get("key", default_value)

# Set for fast lookup
valid_ids: set[int] = {1, 2, 3}
if item_id in valid_ids: ...

# join for strings
result = ",".join(values)

非同期処理パターン

# Concurrent execution
results = await asyncio.gather(task1(), task2(), task3())

# Resource management
async with aiohttp.ClientSession() as session:
    async with session.get(url) as response:
        data = await response.json()

# Concurrency limit
semaphore = asyncio.Semaphore(10)
async with semaphore:
    await do_work()

設計パターン

# Dependency injection (not module-level singletons)
class Service:
    def __init__(self, repository: Repository) -> None:
        self.repository = repository

# Composition root builds the graph once
def create_app(settings: Settings) -> Service:
    return Service(repository=PostgresRepository(settings.dsn))

# Open/Closed: extend via new types, not edits
class JsonFormat:
    def export(self, invoice: Invoice) -> str: ...

# Interface Segregation: small Protocols
class Workable(Protocol):
    def work(self) -> None: ...

# Early return
def process(data: Data | None) -> Result:
    if data is None:
        return Result.empty()
    # main logic here

ドキュメントパターン

def create_user(email: str, name: str) -> User:
    """Create a user account.

    Args:
        email: Unique email address for the account.
        name: Display name for the user.

    Returns:
        The created user.
    """
    return user_repository.create(email=email, name=name)

検証パターン

from pydantic import BaseModel, EmailStr, Field

class CreateUserRequest(BaseModel):
    email: EmailStr
    age: int = Field(ge=0, le=150)

OOP パターン

# Dataclass
@dataclass
class User:
    name: str
    email: str

# Protocol for interfaces
class Repository(Protocol):
    def get(self, id: str) -> Entity: ...

# Property
@property
def full_name(self) -> str:
    return f"{self.first} {self.last}"

関連項目

• 推奨ツール - これらの標準を自動的に適用するツール（ruff、mypy、pytest、pyscn、uv）