========== Call Map

.. default-role:: code

حول

Call Map هي أداة للتنقل في الرسوم البيانية للاستدعاءات في بايثون، مع خطط لدعم لغات أخرى. فيما يلي لقطة شاشة بعد تشغيل call_map -m toolz، ثم النقر على بعض الدوال.

.. figure:: docs/UI-clicked-on-function.png

بينما تهدف Call Map إلى المساعدة في اكتساب فهم عام لقاعدة الشيفرة البرمجية، فهي أيضًا مناسبة بشكل طبيعي لتتبع مسارات الشيفرة، وهو ما يمثل مصدر قلق أمني مهم. تتكشف العديد من القضايا الأمنية من خلال العثور على مسار شيفرة يربط مدخلات المستخدم بأنماط برمجية خطيرة.

انظر منشور المدونة__ لمزيد من التفاصيل.

__ https://www.nccgroup.trust/us/about-us/newsroom-and-events/blog/2017/july/call-map-a-tool-for-navigating-call-graphs-in-python/

التثبيت

يتم توزيع Call Map كحزمة بايثون لـ Python 3.5. للتثبيت باستخدام pip3، قم بتشغيل::

From top level directory of call_map

pip3 install -e .

لاحظ أن بعض توزيعات Python 3 تطلق على مدير الحزم اسم pip، وبعضها يطلقه pip3، لذلك قد تحتاج إلى استبدال pip3 بـ pip.

يجب أن تعمل الأوامر أعلاه على تثبيت الملف التنفيذي call_map في نفس المسار الذي يوجد فيه مُفسِّر بايثون.

للحصول على التفاصيل والطرق البديلة، انظر INSTALL.rst.

بدء سريع

افتح الملفات لبدء الاستكشاف::

call_map -f example.py

you can also open multiple files

call_map -f *.py

يمكنك أيضًا الإضافة إلى مسار البحث عن الوحدات (sys.path)::

call_map -f *.py -p .

ستحاول Call Map حل الملفات كوحدات نمطية كلما أمكن العثور عليها في مسار البحث عن الوحدات. لمزيد من التوثيق حول وسائط سطر الأوامر، استخدم call_map -h.

الإعدادات

لتكوين Call Map، عيّن متغير البيئة CALL_MAP_RC_DIRECTORY. سيكون مسار ملف إعدادات Call Map هو::

$CALL_MAP_RC_DIRECTORY/call_map_rc.py

خيارات الإعداد في الوقت الحالي هي:

• open_in_editor(path: pathlib.Path, line: int): إذا قمت بتعريف هذه الدالة، فسيتم استدعاؤها كلما فتحت ملفًا. على سبيل المثال، يمكن استخدام ما يلي لفتح الملفات في خادم Emacs إذا كنت قد استدعيت server-mode في جلسة Emacs قيد التشغيل::

  def open_in_editor(path, line): import subprocess as sbp sbp.call(['emacsclient', '+{}'.format(line), str(path)])

  يمكن استخدام ما يلي لفتح الملفات في خادم GVim إذا بدأت خادم GVim باستخدام gvim --servername my_vim_server::

  def open_in_editor(path, line): import subprocess as sbp sbp.call(['gvim', '--servername', 'my_vim_server', '--remote', '+{}'.format(line), str(path)])

• MULTITHREADING: ما إذا كان سيتم استخدام مؤشر ترابط منفصل للواجهة الرسومية والبحث في الرسم البياني للاستدعاءات. القيمة الافتراضية هي True. إيقاف تشغيله لأغراض التصحيح.

غرائب

هناك بضع غرائب في تصميم واجهة المستخدم، يعود ذلك إلى أنني لم أتوصل إلى حل أفضل أو أن مقابل التعقيد الإضافي غير مواتٍ.

• يمكن أن تظهر الاستخدامات أكثر من مرة، لكنها في الواقع استخدامات مختلفة في نفس النطاق.

• قد تلاحظ أن بعض الدوال المضمنة مثل help وid وfilter يتم تجاهلها. انظر call_map/config.py في الشيفرة المصدرية للحصول على القائمة الكاملة للدوال التي يتم تجاهلها.

• إذا كان الموضع المراد تمييزه في بداية ملف، فلن يتم تمييزه. وذلك لأن الوحدات والبرامج النصية فقط هي التي توجد عادةً في بداية ملفاتها.

غرائب موروثة من Jedi

بعض الغرائب موروثة من المحرك الخلفي لتحليل بايثون jedi.

• نطاق البحث عن الاستخدامات هو مجموعة الوحدات التي تم تحميلها بواسطة المحرك الخلفي jedi. وهذا يعني أن النطاق سيتغير كلما استكشفت وحدات جديدة. إذا أردت تضمين وحدة بشكل صريح في نطاق البحث، فأضفها إلى القائمة الأولية للوحدات المراد فحصها.

• يبحث jedi دائمًا في sys.path الخاص بالمُفسِّر، حتى عندما لا يكون مضمنًا بشكل صريح. ومع ذلك، فإنه سيعطي الأولوية لـ sys_path المعرّف من قبل المستخدم.

تحفظات

أي تحفظات تنطبق على المحركات الخلفية للتحليل الثابت تنطبق أيضًا على Call Map. (في الوقت الحالي، تم دمج المحرك الخلفي jedi فقط في Call Map.)

Jedi

المحرك الخلفي jedi لتحليل بايثون لا يجد دائمًا جميع الاستخدامات. الطبيعة الديناميكية للغة بايثون تجعل من المستحيل تحديد تعريف الدالة دائمًا من خلال التحليل الثابت. أحيانًا يحل jedi الاستدعاء إلى عدة دوال محتملة. على سبيل المثال، os.path.abspath يعتمد على النظام الأساسي. في هذه الحالة، يسرد call_map كلا الاحتمالين كـ abspath وabspath (2). كما أن jedi لا يحل جميع الاستدعاءات والاستخدامات. توثيق Jedi الخاص يحتوي أيضًا على قائمة التحفظات__.

__ https://jedi.readthedocs.io/en/latest/docs/features.html#caveats

في بعض الأحيان، عندما يرمي Jedi خطأً أثناء تحليل عنصر ما، يؤثر الخطأ على عناصر أخرى. على سبيل المثال، عند البحث عن الاستخدامات، إذا أثار Jedi خطأً في أحد الاستخدامات، فقد تكون الاستخدامات الأخرى التي وجدها غير قابلة للاسترداد (اعتبارًا من Jedi v0.10.0).