python-development

Python 開発標準

ファイルヘッダー

すべての .py ファイルは、次の内容で始める必要があります。

# Copyright (c) Microsoft. All rights reserved.

型注釈

• 戻り値と引数の型は必ず指定します
• Optional[Type] ではなく Type | None を使用します
• 遅延評価を有効にするには、from __future__ import annotations を使用します
• TypeVar 名には接尾辞 T を使用します：ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)
• 読み取り専用の入力引数には MutableMapping ではなく Mapping を使用します
• 内部で呼び出され、実行されるメソッドでは、不要なキャストや isinstance チェックより # type: ignore[...] を優先します ただし、ほかの誤りを見逃さないよう、mypy と pyright の両方で無視対象を具体的に指定してください
• 内部のプライベートヘルパーは、意図がある場合、agent_framework* モジュール間で使用できます。pyright に対応するためだけにヘルパーを公開せず、対象を絞った # pyright: ignore[reportPrivateUsage] を使用してください。
• 型付けに対応するためだけに、単純な受け渡しや1行のヘルパー関数を追加しないでください。設計上の利点がないまま実行時のオーバーヘッドを増やすより、対象を絞った ignore、キャスト、またはより明確な注釈を優先してください。

関数の引数

• 位置引数：完全に想定される引数は最大3つまで
• オプションの引数には、キーワード専用引数（* の後）を使用します
• 追加のインポートを必要としないよう、文字列ベースのオーバーライドを指定します。

def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:
    if isinstance(tool_mode, str):
        tool_mode = ChatToolMode(tool_mode)

• 組み込み名のシャドーイングを避けます（next ではなく next_handler を使用します）
• サブクラスの拡張性に必要な場合を除き、**kwargs は避け、名前付き引数を優先します

Docstring

すべての公開 API には、Google スタイルの docstring を使用します。

def equal(arg1: str, arg2: str) -> bool:
    """Compares two strings and returns True if they are the same.

    Args:
        arg1: The first string to compare.
        arg2: The second string to compare.

    Returns:
        True if the strings are the same, False otherwise.

    Raises:
        ValueError: If one of the strings is empty.
    """

• Agent Framework 固有の例外は必ず記載します
• 該当する場合は、明示的に Keyword Args を使用します
• 標準の Python 例外は、その発生条件が自明でない場合に限り記載します

インポート構成

# Core
from agent_framework import Agent, Message, tool

# Components
from agent_framework.observability import enable_sensitive_telemetry

# Connectors (lazy-loaded)
from agent_framework.openai import OpenAIChatClient
from agent_framework.foundry import FoundryChatClient

公開 API とエクスポート

パッケージレベルの公開 API を定義する __init__.py ファイルでは、直接再エクスポートするインポートと明示的な __all__ を使用します。from ._agents import Agent as Agent のような同一性エイリアスや、 from module import * は避けてください。

内部用の非 __init__.py モジュールでは __all__ を定義しないでください。例外として、agent_framework.observability のように、公開インポート用の窓口として意図的に公開されているモジュールでは __all__ を定義してください。

__all__ = ["Agent", "Message", "ChatResponse"]

from ._agents import Agent
from ._types import Message, ChatResponse

特例：ルートの agent_framework/__init__.py では、実行時に遅延エクスポートを使用します。ルートの公開 API を変更する場合：

• シンボルを _LAZY_MODULE_EXPORTS に追加し、_LAZY_EXPORTS がそこから派生する状態を維持します。
• 明示的な実行時の __all__ との同期を保ちます。from agent_framework import * に必要なため、引き続き必要です。
• pyright、mypy、エディターが型付き API を認識できるよう、同じ公開シンボルを agent_framework/__init__.pyi に追加します。
• 実行時の非推奨動作は、対象モジュールの __getattr__ で実装します。個別の非推奨エクスポートに対するルートレベルの特例分岐は避けてください。
• 同一性エイリアスは、型チェッカーに再エクスポートされた名前を示すため、.pyi スタブでは適切です。特別な互換性上の理由がない限り、実行時の .py モジュールでは避けてください。

パフォーマンスのガイドライン

• 高コストな計算（JSON スキーマ生成など）はキャッシュします
• ホットパスでは isinstance() より、.type 属性に対する match/case を優先します
• 重複したシリアライズを避け、1回だけ計算して再利用します

スタイル

• 行の長さ：120文字
• 変更したファイルのみをフォーマットし、コードベース全体はフォーマットしません
• 引数がほぼ同じ場合は、継承より属性を優先します
• 既定では非同期とし、すべてが非同期であることを前提とします

コネクターの命名規則

• 外部サービス向けのデータを準備するメソッドには _prepare_<object>_for_<purpose> を使用します
• 外部サービスからのデータを処理するメソッドには _parse_<object>_from_<source> を使用します