25.3. وحدة تحكم Python في QGIS

كما سترى لاحقًا في هذا الفصل، صُمّم QGIS وفق بنية تعتمد على الإضافات. يمكن كتابة الإضافات بلغة Python، وهي لغة شهيرة جدًا في المجال الجغرافي المكاني.

يوفّر QGIS واجهة برمجة تطبيقات Python API (راجع PyQGIS Developer Cookbook للاطلاع على بعض أمثلة الشيفرة) لتمكين المستخدم من التفاعل مع كائناته (الطبقات أو المعالم أو الواجهة). كما يتضمن QGIS وحدة تحكم Python.

وحدة تحكم Python في QGIS هي صدفة (shell) تفاعلية لتنفيذ أوامر Python. وتتضمن أيضًا محرّر ملفات Python يتيح لك تحرير سكربتات Python وحفظها. تعتمد كل من وحدة التحكم والمحرّر على الحزمة PyQScintilla2. لفتح وحدة التحكم انتقل إلى Plugins ► Python Console (Ctrl+Alt+P) أو انقر على الأيقونة ^{Python Console} في شريط الأدوات Plugins.

25.3.1. وحدة التحكم التفاعلية

وحدة التحكم مفسّر Python يتيح لك تنفيذ أوامر Python. وحدات QGIS (analysis، core، gui، server، processing، 3d) ووحدات Qt (QtCore، QtGui، QtNetwork، QtWidgets، QtXml) إضافة إلى وحدات Python ‏math وos وre وsys مستوردة مسبقًا ويمكن استخدامها مباشرة.

تتكوّن وحدة التحكم التفاعلية من شريط أدوات ومنطقة إدخال ومنطقة إخراج.

شكل 25.17 وحدة تحكم Python

25.3.1.1. شريط الأدوات

يقدّم شريط الأدوات الأدوات التالية:

• ^{Clear Console} لمسح منطقة الإخراج؛

• ^{Run Command} المتاح في منطقة الإدخال: مماثل للضغط على Enter؛

• ^{Show Editor}: يبدّل إظهار محرّر الشيفرة وإخفاءه؛

• ^Options...: يفتح نافذة حوار لضبط خصائص وحدة التحكم؛

• ^Help... يوفّر قائمة للوصول إلى وثائق مختلفة:

  • تعليمات وحدة تحكم Python (الصفحة الحالية)

  • PyQGIS API documentation

  • PyQGIS Cookbook

• ^{Dock Code Editor} لإرساء اللوحة في واجهة QGIS أو فكّها منها

25.3.1.2. منطقة الإدخال

الميزات الرئيسية لمنطقة الإدخال في وحدة التحكم هي:

• إكمال الشيفرة وتلوين الصياغة وتلميحات الاستدعاء لواجهات API التالية:

  • Python

  • PyQGIS

  • PyQt5

  • QScintilla2

  • osgeo-gdal-ogr

  • osgeo-geos

• Ctrl+Alt+Space لعرض قائمة الإكمال التلقائي إذا كانت مفعّلة في إعدادات Python؛

• تنفيذ مقتطفات الشيفرة من منطقة الإدخال بكتابتها والضغط على Enter أو Run Command؛

• تنفيذ مقتطفات الشيفرة من منطقة الإخراج باستخدام Enter Selected من القائمة السياقية أو بالضغط على Ctrl+E؛

• تصفّح سجل الأوامر من منطقة الإدخال باستخدام مفتاحي الأسهم Up و Down وتنفيذ الأمر الذي تريده؛

• Ctrl+Shift+Space لعرض سجل الأوامر: يؤدي النقر المزدوج على صف إلى تنفيذ الأمر. يمكن أيضًا الوصول إلى نافذة الحوار Command History من القائمة السياقية لمنطقة الإدخال؛

• حفظ سجل الأوامر ومسحه. سيُحفظ السجل في الملف console_history.txt ضمن مجلد ملف تعريف المستخدم النشط؛

• اكتب الأوامر الخاصة التالية:

  • ? لعرض تعليمات وحدة تحكم Python

  • _api لفتح وثائق QGIS C++ API أو _api(object) لوثائق كائن محدد (في وثائق QGIS C++ API أو Qt API)

  • _pyqgis لفتح وثائق QGIS Python API أو _pyqgis(object) لوثائق كائن محدد (في وثائق QGIS Python API أو Qt API)

  • _cookbook لفتح PyQGIS Cookbook.

  • ! متبوعة بأمر لتنفيذ أوامر الصدفة (Shell) من وحدة تحكم Python. ستبدأ وحدة التحكم عملية فرعية وتحوّل مخرجاتها إلى منطقة إخراج وحدة تحكم Python. أثناء تشغيل العملية الفرعية، تتحوّل منطقة إدخال وحدة تحكم Python إلى وضع STDIN وتمرّر الأحرف المُدخلة إلى العملية الابنة. يتيح ذلك إرسال التأكيد عندما يطلبه البرنامج الابن. عندما تكون وحدة التحكم في وضع STDIN، يؤدي الضغط على Ctrl+C إلى إنهاء العملية الفرعية. يمكن أيضًا إسناد نتيجة أمر إلى متغير باستخدام الصياغة var = !cmd

    >>> !echo QGIS Rocks!
    QGIS Rocks
    
    >>> !gdalinfo --version
    GDAL 3.10.3, released 2025/04/01
    
    >>> !pip install black
    # Install black python formatter using pip (if available)
    
    >>> sql_formats = !ogrinfo --formats | grep SQL
    >>> sql_formats
    ['SQLite -vector- (rw+v): SQLite / Spatialite', '  MSSQLSpatial -vector- (rw+): Microsoft SQL Server Spatial Database', '  PostgreSQL -vector- (rw+): PostgreSQL/PostGIS', '  MySQL -vector- (rw+): MySQL', '  PGDUMP -vector- (w+v): PostgreSQL SQL dump']
    

نصيحة

إعادة استخدام الأوامر المنفّذة من لوحة الإخراج

يمكنك تنفيذ مقتطفات الشيفرة من لوحة الإخراج بتحديد نص ما والضغط على Ctrl+E. لا يهم إن كان النص المحدد يحتوي على محث المفسّر (>>>، ...).

25.3.2. محرّر الشيفرة

استخدم الزر ^{Show Editor} في وحدة التحكم التفاعلية لتفعيل عنصر واجهة المحرّر. يتيح تحرير سكربتات Python وحفظها ويقدّم وظائف متقدمة لإدارة شيفرتك. تبعًا لـ الإعدادات المفعّلة، يوفّر قدرات متنوعة لتسهيل كتابة الشيفرة، مثل إكمال الشيفرة وتلوين الصياغة وتلميحات الاستدعاء لواجهات API المدعومة. تتوفر أيضًا الإزاحة التلقائية وإدراج الأقواس والتعليق على الشيفرة وفحص الصياغة.

شكل 25.18 محرّر وحدة تحكم Python

تتيح منطقة محرّر الشيفرة العمل على سكربتات مختلفة في آن واحد، كل منها في تبويب خاص. اضغط ^{New editor} لإضافة تبويب جديد. يمكنك تشغيل سكربت جزئيًا أو كليًا من Code Editor وإخراج النتيجة في منطقة الإخراج بوحدة التحكم التفاعلية.

نصيحة

اضغط Ctrl+Space لعرض قائمة الإكمال التلقائي.

في أعلى نافذة الحوار، يوفّر شريط أدوات الوصول إلى بعض الأوامر. ويوفّر النقر بالزر الأيمن على منطقة المحرّر خيارات إضافية. جميع الأدوات المتاحة موصوفة في الجدول التالي.

جدول 25.1 أدوات محرّر وحدة تحكم Python

اسم الأداة	الوظيفة	الموقع
Open script…	يحمّل ملف Python في نافذة محرّر الشيفرة، في تبويب جديد	شريط الأدوات
Open in external editor…	يفتح سكربت Python محفوظًا في البرنامج الخارجي الافتراضي المعيّن لتحرير ملفات Python
Save (Ctrl+S)	يحفظ السكربت الحالي
Save as… (Ctrl+Shift+S)	يحفظ السكربت الحالي في ملف جديد
Run script (Ctrl+Shift+E)	ينفّذ السكربت كاملًا في وحدة التحكم التفاعلية (ينشئ ذلك ملفًا مترجمًا إلى byte-code بالامتداد .pyc)	شريط الأدوات والقائمة السياقية
Context help (F1)	يحاول عرض التعليمات الخاصة بالسلسلة النصية المحددة (صنف، دالة، كائن،...) في وثائق API المقابلة لها	القائمة السياقية
Run selected (Ctrl+E)	ينفّذ في وحدة التحكم التفاعلية الأسطر المحددة في السكربت	شريط الأدوات والقائمة السياقية
Cut (Ctrl+X)	يقص النص المحدد إلى الحافظة
Copy (Ctrl+C)	ينسخ النص المحدد إلى الحافظة
Paste (Ctrl+V)	يلصق نصًا مقصوصًا أو منسوخًا
Find text	يتيح البحث عن نص في السكربت واستبداله. استخدم اختصار بيئة سطح المكتب الافتراضي للبحث عن التالي/السابق (Ctrl+G و Shift+Ctrl+G)؛ العثور تلقائيًا على أول تطابق عند الكتابة في مربع البحث؛ تعيين سلسلة البحث الأولية إلى التحديد عند فتح البحث؛ فعّل الخيار Use Regular Expressions في شريط البحث لاستخدام التعابير النمطية بدلًا من مطابقة النص العادي؛ Replace لاستبدال النص المطابق بالنص الموجود في مربع الاستبدال. عند استخدام تعبير نمطي، يمكنك الإشارة إلى المجموعات الملتقطة (مثلًا عبر \1) في نص الاستبدال. استخدم Replace All لاستبدال جميع التطابقات دفعة واحدة. يؤدي الضغط على Esc إلى إغلاق شريط البحث.
Toggle comment (Ctrl+:)	يحوّل الأسطر المحددة إلى تعليقات أو يلغي تعليقها، بإضافة الحرف # (متبوعًا بمسافة أحيانًا) أو إزالته من بداية الأسطر. إذا احتوى التحديد على تعليقات وأوامر فعلية معًا، يضيف # في بداية كل سطر غير فارغ. يؤدي الضغط على الزر مرة أخرى إلى العودة إلى الحالة الأولية.
Reformat code (Ctrl+Alt+F)	يتيح تطبيق قواعد تنسيق متنوعة يدويًا على الشيفرة (فرز عبارات الاستيراد، الإزاحة، طول السطر،…)، وفقًا لـ الإعدادات التي يحددها المستخدم. قد يتطلب ذلك تثبيت وحدات Python إضافية.
Object inspector…	يُظهر متصفحًا مخصصًا ويخفيه، يعرض بنية شجرية للأصناف والدوال المتاحة في السكربت. انقر على عنصر للوصول السريع إلى تعريفه. تتطلب الأداة تفعيلها من إعدادات Python - التشغيل والتنقيح.
Hide editor	يخفي كتلة محرّر شيفرة Python. لإظهاره مجددًا، اضغط Show editor button من شريط أدوات وحدة التحكم التفاعلية.	القائمة السياقية
Check syntax (Ctrl+4)	يتصفّح الشيفرة ويبلّغ عن أخطاء الصياغة، مثل الأقواس أو النقطتين المفقودة، أو الإزاحة الخاطئة،…
Undo (Ctrl+Z)	يتراجع عن آخر إجراء
Redo (Ctrl+Shift+Z)	يعيد الإجراءات التي تم التراجع عنها إلى حالة أحدث
Select all (Ctrl+A)	يحدد السكربت بأكمله
Share on GitHub	يشارك السكربت على هيئة Secret Gist أو Public Gist على GitHub، بشرط توفّر رمز وصول GitHub.
Options…	يفتح نافذة الحوار إعدادات Python.