# Sokongan Python dalam Maguyva: Carian Kod dan Refaktor AI

Canonical source: https://maguyva.ai/ms/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 menyokong Python dengan penghuraian AST dan pengekstrakan simbol, membantu ejen AI mengikuti decorator, method self/cls, import, dan kebergantungan merentasi modul dalam repositori Python sebenar.

## Gambaran sokongan

- Peringkat: Sokongan AST dan simbol
- Pengaturcaraan
- Sambungan fail: .py, .pyi, .pyw
- Penghuraian AST sebenar untuk carian sedar-sintaks dan konteks struktur.
- Simbol bernama menyokong carian semantik dan rujukan silang. Navigasi graf tersedia apabila pengekstrakan hubungan didayakan.
- Bahasa ini menyumbang simbol dan hubungan kepada carian berasaskan graf; jenis edge yang disokong berbeza mengikut binaan aslinya.
- Penghuraian AST dan pengekstrakan simbol kedua-duanya tersedia.

## Paling sesuai

- Repositori FastAPI, Django, platform data, atau alatan dalaman di mana kod aplikasi dan skrip operasi hidup bersama.
- Pasukan yang merefaktor service Python yang telah lama wujud dan sudah mempunyai decorator, jobs latar belakang, dan banyak perhubungan tersirat.
- Aliran kerja ejen yang memerlukan lebih daripada grep sebelum menukar handler, service, model, atau helper.

## Aliran kerja ejen

- Menjejaki endpoint, task, atau arahan CLI melalui helper dan modul kongsi sebelum menyuntingnya.
- Mencari di mana service, class, atau fungsi utiliti dijadikan instance dan digunakan semula merentasi repositori.
- Membandingkan pelaksanaan bersebelahan supaya ejen menyunting abstraksi yang betul, bukan padanan string yang paling hampir.

## Mengapa alatan AI yang memahami kod secara cetek sering gagal dalam repositori Python

Python adalah tempat banyak alatan pengekodan AI kelihatan baik pada mulanya dan kemudian mula meneka dalam produksi. Bahagian yang sukar sudah biasa: titik masuk berdecorator, kelas service, type stub, modul helper kecil di mana-mana, dan method yang hanya bermakna sebaik sahaja anda menghubungkan semula `self` atau `cls` kepada class yang mengandungi method tersebut.

Untuk Python, persoalan sebenar bukan "bolehkah ia membaca fail `.py`?" Persoalannya ialah sama ada ejen dapat kekal berasaskan bukti semasa ia bergerak daripada endpoint ke service, daripada task latar belakang ke helper, atau daripada nama class kepada method yang benar-benar melaksanakan gelagat itu.

## Apa yang Maguyva sebenarnya ekstrak dalam Python

Maguyva menganggap Python sebagai bahasa struktural yang lengkap. Konfigurasi merangkumi `.py`, `.pyw`, dan `.pyi`; memetakan `decorated_definition` semula kepada simbol fungsi; dan memautkan panggilan method `self` / `cls` kepada class yang melingkunginya. Itu penting kerana itulah tepat tempat repositori Python mula terasa jelas kepada manusia tetapi kabur kepada LLM.

Ia juga menapis banyak panggilan pustaka piawai yang tidak relevan daripada pengekstrakan hubungan. Ini bermakna panggilan runtime lazim daripada modul seperti `pathlib`, `typing`, atau `logging` kurang berkemungkinan menenggelamkan hubungan khusus repositori yang benar-benar anda pedulikan.

## Aliran kerja MCP yang berguna untuk repositori Python

Aliran kerja paling mudah dan berguna ialah:

- Mulakan dengan `intelligent_search` untuk soalan gelagat seperti "logik cuba semula di sekeliling penyegerakan invois" atau "semakan kebenaran dalam endpoint bil".
- Beralih kepada `find_symbol` sebaik sahaja anda tahu nama class atau fungsi yang anda pedulikan.
- Gunakan `dependency_search` dengan penelusuran masuk sebelum merefaktor service, helper, atau base class kongsi.

Corak itu lebih baik daripada meminta ejen "kemas kini aliran bil" tanpa konteks awal. Ia membenarkan ejen membina peta dahulu dan menukar kod kemudian.

## Bila halaman ini berguna

Halaman ini untuk repositori Python yang sudah mempunyai sedikit usia dan kerumitan: kod service, jobs, skrip, jenis yang dijana, dan config sekeliling. Jika perbandingan utama anda merentasi monorepo web polyglot, baca [panduan TypeScript](/ms/languages/typescript) juga. Jika anda hanya memerlukan matriks sokongan penuh, gunakan [keserasian](/ms/docs/compatibility).

## Butiran enjin

- Definisi yang berdekorator masih dianggap sebagai fungsi, jadi view dan task berdekorator kekal boleh dicari sebagai simbol.
- Panggilan kaedah `self` dan `cls` dikaitkan semula kepada class yang mengandunginya, yang membantu graf kekal berguna dalam kod servis yang banyak class.
- Penormal import, panggilan, dan simbol diaktifkan manakala bunyi bising stdlib biasa seperti `pathlib.*`, `typing.*`, dan `logging.*` ditapis daripada perhubungan.

## Titik masuk MCP yang berguna

- `intelligent_search`: Mula dengan pertanyaan konseptual seperti “logik cuba semula sekitar penyegerakan invois” dan tetapkan `language_filter="python"` kalau repo itu menggunakan pelbagai bahasa.
- `find_symbol`: Guna ia apabila anda tahu nama class atau fungsi dan perlukan definisi berserta rujukan sebelum menyunting.
- `dependency_search`: Guna arah masuk sebelum refactor servis atau helper yang dikongsi untuk lihat apa yang bergantung padanya.