ローカルデバッグ — Python

Last updated on July 14, 2026

注釈：本資料はAI技術を用いて翻訳されています。

このガイドでは、Python で記述された Extend アプリのデバッグに固有の内容をすべて説明します。 すべての Extend アプリと言語に共通する概念（環境変数、VS Code の デバッグワークフロー、ログの読み方、よくある問題）については、 Extend ローカルデバッグガイドを参照してください。

前提条件​

  • Python 3.10 以降 — 以下で確認してください。

    python3 --version
    # Expected: Python 3.10.x or later

  • VS Code Python 拡張機能（ms-python.python） — VS Code マーケットプレイスからインストールするか、 リポジトリを開いたときに表示される推奨拡張機能のインストールを承認してください。

  • debugpy — VS Code 用の Python デバッグアダプターです。最新の VS Code バージョンは debugpy を自動的にバンドルしています。含まれていない場合は次のようにします。

    pyproject.toml を変更せずに一時的にインストールします。

    uv run --with debugpy python -m debugpy --version

  • AccelByte の認証情報 — AB_BASE_URL、AB_CLIENT_ID、AB_CLIENT_SECRET。 メインガイドの環境のセットアップを参照してください。

VS Code の起動設定​

リポジトリには、.vscode/launch.json にすぐに使える起動設定が用意されています。

{
  "name": "Debug: App",
  "type": "debugpy",
  "request": "launch",
  "module": "app",
  "cwd": "${workspaceFolder}",
  "env": { "PYTHONPATH": "src" },
  "envFile": "${workspaceFolder}/.env",
  "console": "integratedTerminal",
  "justMyCode": true
}

正確な設定はアプリテンプレートの .vscode/launch.json で提供されているため、上記の値と異なる場合はそこからコピーしてください。

手順:

  1. .env に値を入力します（環境のセットアップを参照）。
  2. Run and Debug パネルを開きます（Ctrl+Shift+D / Cmd+Shift+D）。
  3. ドロップダウンから "Debug: App" を選択します。
  4. F5 を押します。

その他の IDE — リモート debugpy アタッチ​

debugpy をポート 5678 でリスニングさせてアプリを起動します。

export $(grep -v '^#' .env | xargs)
PYTHONPATH=src uv run --with debugpy python -m debugpy --listen 5678 --wait-for-client -m app

プロセスはデバッガーが接続するまで一時停止します。PyCharm または 2 つ目の VS Code ウィンドウからアタッチします。

{
  "name": "Attach: Remote",
  "type": "debugpy",
  "request": "attach",
  "connect": { "host": "localhost", "port": 5678 }
}

条件付きブレークポイントの構文​

ブレークポイントを右クリック → Edit Breakpoint → Python の式を入力します。例:

request.user_id == "user_001"

デバッガーは条件が true の場合のみ一時停止します。

jq を使ったログの読み取り​

# Pretty-print everything (Docker)
docker compose logs -f app | jq '.'

# Show only ERROR lines (Docker)
docker compose logs -f app | jq 'select(.level == "ERROR")'

コンテナ外の場合:

PYTHONPATH=src uv run python -m app 2>&1 | jq '.'

ログ形式とログレベルの概要については、メインガイドの ログの読み取りと理解を参照してください。

Python 固有のトラブルシューティング​

app に対する ModuleNotFoundError​

症状: python -m app を実行すると ModuleNotFoundError: No module named 'app' が表示されます。

原因: 作業ディレクトリが間違っています。モジュールは src/ 配下にあります。

修正方法:

PYTHONPATH=src uv run python -m app

debugpy が見つからない​

症状: VS Code が debugpy はインストールされていないと表示します。

修正方法:

uv add --dev debugpy

ポートの競合を確認する​

ss -tlnp | grep -E '6565|8000|8080|5678'

古くなったプロセスを終了して再度開始してください。

参考資料​

に最終更新
On this page