# دعم Maguyva للغة Python: بحث الكود وإعادة الهيكلة بالذكاء الاصطناعي

Canonical source: https://maguyva.ai/ar/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 لغة Python عبر تحليل AST واستخلاص الرموز، مما يساعد وكلاء الذكاء الاصطناعي على تتبّع المُزخرِفات، ودوال self/cls، والاستيرادات، والتبعيات عبر الوحدات في مستودعات Python الحقيقية.

## لمحة عن الدعم

- المستوى: دعم AST والرموز
- البرمجة
- الامتدادات: .py, .pyi, .pyw
- تحليل AST حقيقي لبحث واعٍ بالصياغة النحوية وسياق بنيوي.
- تُغذّي الرموز المسمّاة البحث الدلالي والمراجع المتقاطعة. ويتوفر التنقل عبر الرسم البياني عند تمكين استخراج العلاقات.
- تُسهم هذه اللغة بالرموز والعلاقات في البحث المراعي لبنية الرسم البياني؛ وتختلف أنواع الحواف المدعومة بحسب التراكيب الأصلية في اللغة.
- يتوفر كل من تحليل AST واستخلاص الرموز.

## الأنسب لـ

- مستودعات FastAPI أو Django أو منصات بيانات أو أدوات داخلية حيث يتعايش كود التطبيق مع النصوص البرمجية التشغيلية.
- فرق تعيد هيكلة خدمات Python طويلة العمر تحتوي بالفعل على مُزخرِفات، ومهام خلفية، وقدر كبير من الربط الضمني.
- سير عمل للوكلاء يحتاج إلى أكثر من مجرد grep قبل تغيير معالِج أو خدمة أو نموذج أو دالة مساعدة.

## سير عمل الوكلاء

- تتبّع نقطة نهاية أو مهمة أو أمر سطر أوامر (CLI) عبر الدوال المساعدة والوحدات المشتركة قبل تعديله.
- إيجاد أين يتم إنشاء وإعادة استخدام خدمة أو صنف أو دالة مساعدة عبر المستودع.
- مقارنة التنفيذات المجاورة كي يعدِّل الوكيل التجريد الصحيح بدلًا من أقرب مطابقة نصية.

## أين تكسر مستودعات Python عادةً أدوات الذكاء الاصطناعي السطحية

Python هي حيث تبدو الكثير من أدوات البرمجة بالذكاء الاصطناعي جيدة في البداية ثم تبدأ بالتخمين في الإنتاج. الأجزاء الصعبة مألوفة: نقاط دخول مُزخرَفة، وأصناف خدمة، وملفات الأنواع النائبة، ووحدات مساعدة صغيرة في كل مكان، ودوال لا معنى لها إلا بعد إعادة ربط `self` أو `cls` بالصنف الذي تنتمي إليه.

بالنسبة إلى Python، السؤال الحقيقي ليس "هل يستطيع قراءة ملفات `.py`؟" السؤال هو ما إذا كان الوكيل قادرًا على البقاء مرتكزًا وهو ينتقل من نقطة نهاية إلى خدمة، ومن مهمة خلفية إلى دالة مساعدة، أو من اسم صنف إلى الدوال التي تنفِّذ السلوك فعليًا.

## ما الذي يستخلصه Maguyva فعليًا في Python

يعامل Maguyva لغة Python كلغة بنيوية كاملة. يغطي الإعداد `.py` و`.pyw` و`.pyi`؛ ويربط `decorated_definition` مرة أخرى برمز الدالة؛ ويُسنِد استدعاءات دوال `self` / `cls` مرة أخرى إلى الصنف المحيط. وهذا مهم لأن تلك هي بالضبط المواضع التي تبدأ فيها مستودعات Python بالظهور واضحة للإنسان وغامضة لـLLM.

كما يُصفِّي قدرًا كبيرًا من ضجيج المكتبة القياسية من استخلاص العلاقات. وهذا يعني أن استدعاءات وقت التشغيل الشائعة من وحدات مثل `pathlib` أو `typing` أو `logging` أقل عرضة لأن تطغى على العلاقات الخاصة بالمستودع التي تهمك فعليًا.

## سير عمل MCP مفيد لمستودعات Python

أبسط سير عمل مفيد هو:

- ابدأ بـ`intelligent_search` لسؤال على مستوى السلوك مثل "منطق إعادة المحاولة حول مزامنة الفواتير" أو "فحوصات الصلاحيات في نقاط نهاية الفوترة".
- انتقل إلى `find_symbol` متى عرفت اسم الصنف أو الدالة التي تهمك.
- استخدم `dependency_search` مع اجتياز وارد قبل إعادة هيكلة خدمة مشتركة أو دالة مساعدة أو صنف أساس.

هذا النمط أفضل من أن تطلب من الوكيل "تحديث تدفق الفوترة" بدايةً من الصفر. فهو يتيح للوكيل بناء خريطة أولًا وتغيير الكود ثانيًا.

## متى تكون هذه الصفحة مفيدة

هذه الصفحة مخصصة لمستودعات Python التي لديها بالفعل قدر من القِدَم والتعقيد: كود الخدمات، والمهام، والنصوص البرمجية، والأنواع المُولَّدة، والإعداد المحيط. إذا كانت مقارنتك الرئيسية عبر المستودعات الأحادية متعددة اللغات لتطبيقات الويب، اقرأ [دليل TypeScript](/ar/languages/typescript) أيضًا. وإذا كنت تحتاج فقط إلى مصفوفة الدعم الكاملة، استخدم [التوافق](/ar/docs/compatibility).

## تفاصيل المحرك

- تظلّ التعريفات المزوّدة بالمُزيّنات تُعامَل كدوال، لذا تبقى طرق العرض والمهام المزوّدة بها قابلة للبحث كرموز.
- تُنسَب استدعاءات التوابع عبر `self` و`cls` إلى الصنف المحيط بها، ما يساعد الرسم البياني على البقاء مفيدًا في شيفرة الخدمات كثيفة الأصناف.
- مُطبِّعات الاستيراد والاستدعاء والرموز مُفعَّلة، بينما تُصفَّى ضوضاء المكتبة القياسية الشائعة مثل `pathlib.*` و`typing.*` و`logging.*` من العلاقات.

## نقاط دخول مفيدة عبر MCP

- `intelligent_search`: ابدأ باستعلام مفاهيمي مثل "منطق إعادة المحاولة حول مزامنة الفواتير"، واضبط `language_filter="python"` إذا كان المستودع متعدد اللغات.
- `find_symbol`: استخدمه حين تعرف اسم الصنف أو الدالة وتحتاج إلى التعريف مع المراجع قبل التحرير.
- `dependency_search`: استخدم الاتجاه الوارد (incoming) قبل إعادة هيكلة خدمة أو دالة مساعدة مشتركة لمعرفة ما يعتمد عليها.