moai-lang-python

クイックリファレンス（30秒）

Python 3.13 以降の開発スペシャリスト：FastAPI、Django、非同期パターン、pytest、最新の Python 機能に対応します。

自動トリガー：.py 拡張子の Python ファイル、pyproject.toml、requirements.txt、pytest.ini、FastAPI または Django に関する議論

主な機能：

• Python 3.13 の機能：PEP 744 による JIT コンパイラー、PEP 703 による GIL フリーモード、match および case 文によるパターンマッチング
• Web フレームワーク：FastAPI 0.115 以降、Django 5.2 LTS
• データ検証：model_validate パターンを使用する Pydantic v2.9
• ORM：SQLAlchemy 2.0 の非同期パターン
• テスト：フィクスチャ、非同期テスト、parametrize デコレーターを使用する pytest
• パッケージ管理：pyproject.toml を使用する poetry、uv、pip
• 型ヒント：Protocol、TypeVar、ParamSpec、最新の型付けパターン
• 非同期処理：asyncio、非同期ジェネレーター、タスクグループ
• データサイエンス：numpy、pandas、polars の基本

クイックパターン

FastAPI エンドポイントパターン：

fastapi から FastAPI と Depends を、pydantic から BaseModel をインポートします。FastAPI アプリケーションのインスタンスを作成します。BaseModel を継承する UserCreate モデルクラスを定義し、name と email の文字列フィールドを追加します。users パスに非同期 POST エンドポイントを作成します。このエンドポイントは UserCreate パラメーターを受け取り、await を使って UserService.create を呼び出し、結果を返します。

Pydantic v2.9 の検証パターン：

pydantic から BaseModel と ConfigDict をインポートします。BaseModel を継承する User クラスを定義します。ConfigDict で from_attributes を True、str_strip_whitespace を True に設定し、model_config を設定します。id を整数、name と email を文字列のフィールドとして追加します。ORM オブジェクトからインスタンスを作成するには model_validate を、JSON データから作成するには model_validate_json を使用します。

pytest の非同期テストパターン：

pytest をインポートし、pytest.mark.asyncio デコレーターをテスト関数に付けます。フィクスチャパラメーターとして async_client を受け取る非同期テスト関数を作成します。name フィールドを含む JSON ボディを指定して、users エンドポイントに POST リクエストを送信します。レスポンスの status_code が 201 であることをアサートします。

---

実装ガイド（5分）

Python 3.13 の新機能

PEP 744 による JIT コンパイラー：

• 実験的な機能で、デフォルトでは無効です
• PYTHON_JIT 環境変数を 1 に設定して有効にします
• ビルドオプションとして enable-experimental-jit を利用できます
• CPU バウンドのコードのパフォーマンスを向上させます
• 特化されたバイトコードをマシンコードに変換する copy-and-patch JIT を使用します

PEP 703 による GIL フリーモード：

• 実験的なフリースレッドビルドを python3.13t として利用できます
• スレッドの真の並列実行を可能にします
• Windows および macOS の公式インストーラーで利用できます
• CPU 負荷の高いマルチスレッドアプリケーションに最適です
• 現時点では本番環境での使用は推奨されません

match と case によるパターンマッチング：

response 辞書を受け取り、文字列を返す process_response 関数を作成します。response に対して match 文を使用します。status が ok で data フィールドを含む case では、data を含む成功メッセージを返します。status が error で message フィールドを含む case では、エラーメッセージを返します。ガード条件を使って status が pending または processing に一致する case では、処理中メッセージを返します。アンダースコアを使ったデフォルトの case では、不明なレスポンスを返します。

FastAPI 0.115+ のパターン

非同期の依存性注入：

fastapi から FastAPI と Depends、sqlalchemy.ext.asyncio から AsyncSession、contextlib から asynccontextmanager をインポートします。asynccontextmanager でデコレートし、FastAPI アプリを受け取る lifespan 非同期コンテキストマネージャーを作成します。lifespan の中で、起動時に await init_db を呼び出し、yield してから、シャットダウン時に await cleanup を呼び出します。lifespan パラメーターを指定して FastAPI アプリを作成します。AsyncSession の AsyncGenerator を返す非同期の get_db 関数を定義します。この関数では async_session を async with で使用し、セッションを yield します。user_id パスパラメーターを持つ users 用の get エンドポイントを作成し、Depends で get_db を指定してデータベースセッションを注入します。await get_user_by_id を呼び出し、そのユーザーを使って UserResponse.model_validate を返します。

クラスベースの依存関係：

page のデフォルト値を 1、size のデフォルト値を 20 として受け取る init メソッドを持つ Paginator クラスを作成します。self.page を 1 と page の最大値、self.size を 100 と 1 と size の最大値の最小値、self.offset を page から 1 を引いた値に size を掛けた値に設定します。Depends で Paginator を指定してページネーションを注入する list_items エンドポイントを作成し、offset と size を指定して get_page を使い、アイテムを返します。

Django 5.2 LTS の機能

複合主キー：

Order を参照し、削除時に CASCADE を指定する ForeignKey、Product を参照し、削除時に CASCADE を指定する ForeignKey、および quantity 用の IntegerField を持つ OrderItem モデルを作成します。Meta クラスで、order と product のフィールドを使って pk を models.CompositePrimaryKey に設定します。

クエリパラメーターを含む URL の逆引き：

django.urls から reverse をインポートします。検索ビュー名、q を django、page を 1 に設定した query 辞書、そして results に設定した fragment を指定して reverse を呼び出します。結果は、クエリー文字列とフラグメントを含む検索パスです。

シェルでのモデルの自動インポート：

python manage.py shell を実行すると、明示的な import 文がなくても、すべてのインストール済みアプリのモデルが自動的にインポートされます。

Pydantic v2.9 の高度なパターン

Annotated を使った再利用可能なバリデーター：

typing から Annotated、pydantic から AfterValidator と BaseModel をインポートします。整数 v を受け取り、整数を返す validate_positive 関数を定義します。v が 0 以下の場合は、「正の値である必要があります」というメッセージとともに ValueError を送出します。それ以外の場合は v を返します。int と validate_positive を使った AfterValidator を含む Annotated として PositiveInt を作成します。price と quantity のモデルフィールドに PositiveInt を使用します。

フィールド間の検証に使うモデルバリデーター：

pydantic から BaseModel と model_validator、typing から Self をインポートします。start_date と end_date を date フィールドとして持つ DateRange モデルを作成します。mode を after に設定した model_validator デコレーターを追加します。Self を返す validate_dates メソッドで、end_date が start_date より前かどうかを確認し、そうであれば ValueError を送出します。そうでなければ self を返します。

ConfigDict のベストプラクティス：

model_config を ConfigDict に設定した BaseSchema モデルを作成します。ORM オブジェクトをサポートするために from_attributes を True に、エイリアスを許可するために populate_by_name を True に、未知のフィールドでエラーにするために extra を forbid に、文字列を整えるために str_strip_whitespace を True に設定します。

SQLAlchemy 2.0 非同期パターン

エンジンとセッションの設定：

sqlalchemy.ext.asyncio から create_async_engine、async_sessionmaker、AsyncSession をインポートします。postgresql+asyncpg の接続文字列を指定し、pool_pre_ping を True、echo を True に設定して、create_async_engine でエンジンを作成します。エンジンを指定し、class_ を AsyncSession、expire_on_commit を False に設定して async_sessionmaker で async_session を作成します。これにより、デタッチされたインスタンスのエラーを防ぎます。

リポジトリパターン：

AsyncSession を受け取る init メソッドを持つ UserRepository クラスを作成します。user_id の where 句を含む select クエリを実行し、scalar_one_or_none の結果を返す非同期の get_by_id メソッドを定義します。UserCreate の model_dump から User を作成し、セッションに追加してコミット、リフレッシュした後、ユーザーを返す非同期の create メソッドを定義します。

大量の結果のストリーミング：

AsyncSession を受け取る非同期の stream_users 関数を作成します。select User クエリを指定して await db.stream を呼び出します。async for で result.scalars を反復処理し、各ユーザーを yield します。

pytest の高度なパターン

pytest-asyncio による非同期フィクスチャ：

httpx から pytest、pytest_asyncio、AsyncClient をインポートします。フィクスチャに pytest_asyncio.fixture デコレーターを適用します。AsyncClient を app と base_url とともに async with で使用し、クライアントを yield する async_client フィクスチャを作成します。async_session と session.begin を async with で使用し、セッションを yield して await session.rollback を呼び出す db_session フィクスチャを作成します。

パラメーター化テスト：

input_data と expected_status をパラメーター名として、pytest.mark.parametrize デコレーターを使用します。辞書と期待するステータスコードを組み合わせたタプルでテストケースを指定します。valid、empty_name、missing_name のケースに ids を追加します。テスト関数では async_client、input_data、expected_status を受け取り、users エンドポイントに POST リクエストを送信して、status_code が期待値と一致することをアサートします。

フィクスチャファクトリー：

非同期関数を返す user_factory フィクスチャを作成します。内部関数は AsyncSession の db とキーワード引数を受け取ります。name と email を含む defaults 辞書を設定します。defaults と kwargs をパイプ演算子でマージして User を作成し、db に追加してコミットした後、ユーザーを返します。

型ヒントの最新パターン

構造的部分型付けのための Protocol：

typing から Protocol と runtime_checkable をインポートします。runtime_checkable デコレーターを適用します。ジェネリック型 T を使って Repository Protocol を定義します。int 型の id を受け取り、T または None を返す抽象非同期 get メソッド、dict 型の data を受け取り T を返す非同期 create メソッド、int 型の id を受け取り bool を返す非同期 delete メソッドを追加します。

デコレーター用 ParamSpec：

typing から ParamSpec、TypeVar、Callable を、functools から wraps をインポートします。P を ParamSpec、R を TypeVar として定義します。times のデフォルト値を 3 とする retry デコレーター関数を作成し、呼び出し可能なラッパーを返します。内部デコレーターで関数をラップし、ラッパーは指定された回数だけ反復処理して関数を await し、最後の試行では例外を再送出します。

パッケージ管理

Poetry を使用した pyproject.toml：

tool.poetry セクションで name、version、Python のバージョン制約を設定します。dependencies に fastapi、pydantic、asyncio エクストラ付きの sqlalchemy を追加します。dev dependencies に pytest、pytest-asyncio、ruff を追加します。ruff の line-length と target-version を設定します。ini_options で pytest の asyncio_mode を auto に設定します。

高速なパッケージマネージャー uv：

astral.sh のインストールスクリプトを curl で使用して uv をインストールします。uv venv で仮想環境を作成します。uv pip install で requirements.txt から依存関係をインストールします。uv add コマンドで依存関係を追加します。

---

高度な実装（10 分以上）

以下を含む包括的な内容については、次を参照してください。

• Docker と Kubernetes の本番環境へのデプロイパターン
• タスクグループやセマフォを含む高度な非同期パターン
• numpy、pandas、polars とのデータサイエンス統合
• パフォーマンス最適化手法
• OWASP パターンに沿ったセキュリティのベストプラクティス
• CI/CD 統合パターン

参照先：

• 完全なリファレンスドキュメントについては reference.md
• 本番環境ですぐに使えるコード例については examples.md

---

Context7 ライブラリマッピング

• tiangolo/fastapi：FastAPI 非同期 Web フレームワーク
• django/django：Django Web フレームワーク
• pydantic/pydantic：型アノテーションを使ったデータ検証
• sqlalchemy/sqlalchemy：SQL ツールキットおよび ORM
• pytest-dev/pytest：テストフレームワーク
• numpy/numpy：数値計算
• pandas-dev/pandas：データ分析ライブラリ
• pola-rs/polars：高速な DataFrame ライブラリ

---

相性の良いツール

• moai-domain-backend：REST API とマイクロサービスアーキテクチャ
• moai-domain-database：SQL パターンと ORM の最適化
• moai-workflow-testing：DDD とテスト戦略
• moai-essentials-debug：AI を活用したデバッグ
• moai-foundation-quality：TRUST 5 品質原則

---

トラブルシューティング

よくある問題：

Python バージョンの確認：

バージョンフラグを付けて python を実行し、3.13 以降であることを確認します。詳細なバージョン情報を表示するには、-c フラグを付けた python を使って sys.version_info を出力します。

非同期セッションのデタッチエラー：

セッション設定で expire_on_commit を False に設定します。または、コミット後にオブジェクトに対して await session.refresh を使用します。

pytest asyncio モードの警告：

pyproject.toml の tool.pytest.ini_options で、asyncio_mode を auto に、asyncio_default_fixture_loop_scope を function に設定します。

Pydantic v2 への移行：

parse_obj メソッドは model_validate に変更されました。parse_raw メソッドは model_validate_json に変更されました。from_orm の機能を使うには、ConfigDict で from_attributes を True に設定する必要があります。

---

最終更新日：2026-01-11 ステータス：有効（v1.1.0）