# MaguyvaのPython対応: AIによるコード検索とリファクタリング

Canonical source: https://maguyva.ai/ja/languages/python

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

MaguyvaはAST解析とシンボル抽出によりPythonに対応しており、AIエージェントが実際のPythonリポジトリにおいてデコレータ、self/clsメソッド、インポート、モジュール横断の依存関係をたどるのを助けます。

## 対応状況スナップショット

- 対応レベル: AST・シンボル対応
- プログラミング
- 拡張子: .py, .pyi, .pyw
- 構文を考慮した検索と構造コンテキストのための実際のAST解析。
- 名前付きシンボルはセマンティック検索と相互参照に利用されます。関係抽出が有効な場合は、グラフナビゲーションも利用できます。
- この言語は、グラフを考慮した検索にシンボルと関係情報を提供します。対応するエッジの種類は、その言語固有の構文要素によって異なります。
- AST解析とシンボル抽出の両方に対応しています。

## 最適な用途

- アプリケーションコードと運用スクリプトが同居する、FastAPI、Django、データプラットフォーム、社内ツールのリポジトリ。
- すでにデコレータ、バックグラウンドジョブ、そして多くの暗黙的な配線を抱えた、息の長いPythonサービスをリファクタリングするチーム。
- ハンドラー、サービス、モデル、ヘルパーを変更する前に、grep以上のものを必要とするエージェントワークフロー。

## エージェントワークフロー

- 編集する前に、エンドポイント、タスク、CLIコマンドをヘルパーや共有モジュールを通じてたどる。
- サービス、クラス、ユーティリティ関数がリポジトリ全体のどこでインスタンス化・再利用されているかを見つける。
- エージェントが最も近い文字列一致ではなく正しい抽象化を編集するように、隣接する実装同士を比較する。

## Pythonのリポジトリが浅いAIツールを破綻させやすい理由

Pythonは、多くのAIコーディングツールが最初は良さそうに見えて、やがて本番環境で当てずっぽうを始める場所です。難しい部分はおなじみのものです。デコレータの付いたエントリポイント、サービスクラス、型スタブ、至るところにある小さなヘルパーモジュール、そして`self`や`cls`を所属するクラスに結び直して初めて意味をなすメソッドなどです。

Pythonにとって本当の問いは「`.py`ファイルを読めるか」ではありません。問いは、エンドポイントからサービスへ、バックグラウンドタスクからヘルパーへ、あるいはクラス名から実際に挙動を実装しているメソッドへと移動する間、エージェントが根拠を保ち続けられるかどうかです。

## MaguyvaがPythonで実際に抽出するもの

Maguyvaは、Pythonのコード構造を本格的に解析します。この設定は`.py`、`.pyw`、`.pyi`をカバーし、`decorated_definition`を関数シンボルに対応付け、`self` / `cls`のメソッド呼び出しを囲むクラスに紐づけます。これが重要なのは、まさにそこがPythonのリポジトリが人間にとっては自明で、LLMにとっては曖昧に感じられ始める場所だからです。

また、標準ライブラリのノイズの多くを関係抽出からフィルタリングします。つまり、`pathlib`、`typing`、`logging`のようなモジュールからの一般的なランタイム呼び出しが、本当に気にすべきリポジトリ固有の関係性を埋もれさせにくくなります。

## Pythonのリポジトリに役立つMCPワークフロー

最もシンプルで役立つワークフローは、次のとおりです。

- 「請求書同期まわりのリトライロジック」や「課金エンドポイントにおける権限チェック」のような挙動に関する疑問には`intelligent_search`から始める。
- 気になるクラス名や関数名が分かったら`find_symbol`に切り替える。
- 共有サービス、ヘルパー、基底クラスをリファクタリングする前に、incomingトラバーサルで`dependency_search`を使う。

このパターンは、コールドスタートの状態でエージェントに「課金フローを更新して」と頼むよりも優れています。エージェントがまず地図を作り、その後でコードを変更できるようになるからです。

## このページが役立つ場面

このページは、サービスコード、ジョブ、スクリプト、生成された型、周辺の設定など、すでにある程度の年月と複雑さを抱えたPythonリポジトリのためのものです。主な比較対象がポリグロットなWebモノレポ全般であれば、[TypeScriptガイド](/ja/languages/typescript)も読んでみてください。対応マトリクス全体だけが必要な場合は、[互換性](/ja/docs/compatibility)をご覧ください。

## エンジンの詳細

- デコレータが付いた定義も関数として扱われるため、デコレートされたビューやタスクもシンボルとして検索可能です。
- `self` や `cls` によるメソッド呼び出しは、それを含むクラスに紐づけて解決されるため、クラス中心のサービスコードでもグラフが実用的な状態を保てます。
- import・呼び出し・シンボルの正規化は有効になっている一方、`pathlib.*`、`typing.*`、`logging.*` など一般的な標準ライブラリのノイズは関係性から除外されます。

## 役立つMCPエントリーポイント

- `intelligent_search`: 「請求書同期まわりのリトライロジック」のような概念的なクエリから始め、リポジトリがポリグロットであれば `language_filter="python"` を設定してください。
- `find_symbol`: クラス名や関数名が分かっていて、編集前に定義と参照の両方が必要なときに使用してください。
- `dependency_search`: 共有サービスやヘルパーをリファクタリングする前に、incoming方向を使って何がそれに依存しているかを確認してください。