1. المقدمة

يهدف هذا المستند إلى أن يكون درسًا تعليميًا ودليلًا مرجعيًا في آن واحد. ومع أنه لا يسرد جميع حالات الاستخدام الممكنة، فإنه يقدّم نظرة عامة جيدة على الوظائف الرئيسية.

يُسمح بنسخ هذا المستند وتوزيعه و/أو تعديله وفق شروط رخصة GNU Free Documentation License، الإصدار 1.3 أو أي إصدار لاحق تنشره Free Software Foundation؛ دون أقسام ثابتة، ودون نصوص للغلاف الأمامي، ودون نصوص للغلاف الخلفي.

توجد نسخة من الرخصة في القسم رخصة للوثائق الحرة GNU.

تنطبق هذه الرخصة أيضًا على جميع مقتطفات الشيفرة في هذا المستند.

قُدّم دعم Python لأول مرة في QGIS 0.9. وهناك عدة طرق لاستخدام Python في QGIS Desktop (تتناولها الأقسام التالية):

• تنفيذ الأوامر في وحدة تحكم Python داخل QGIS

• إنشاء الإضافات واستخدامها

• تشغيل شيفرة Python تلقائيًا عند بدء QGIS

• إنشاء خوارزميات معالجة

• إنشاء دوال للتعبيرات في QGIS

• إنشاء تطبيقات مخصّصة مبنية على QGIS API

تتوفر روابط Python أيضًا لـ QGIS Server، بما في ذلك إضافات Python (انظر خادم QGIS ولغة Python) وروابط Python يمكن استخدامها لتضمين QGIS Server في تطبيق Python.

يتوفر مرجع complete QGIS C++ API الذي يوثّق الأصناف الموجودة في مكتبات QGIS. أما The Pythonic QGIS API (pyqgis) فهي مطابقة تقريبًا لواجهة C++ API.

ومن المصادر الجيدة الأخرى لتعلّم تنفيذ المهام الشائعة تنزيل إضافات موجودة من مستودع الإضافات وفحص شيفرتها.

1.1. كتابة السكربتات في وحدة تحكم Python

يوفّر QGIS وحدة تحكم Python مدمجة لكتابة السكربتات. يمكن فتحها من القائمة Plugins ► Python Console:

شكل 1.11 وحدة تحكم Python في QGIS

توضّح لقطة الشاشة أعلاه كيفية الحصول على الطبقة المحدّدة حاليًا في قائمة الطبقات، وعرض معرّفها، وعرض عدد المعالم إن كانت طبقة متجهية. وللتفاعل مع بيئة QGIS يتوفر المتغير iface، وهو نسخة من الصنف QgisInterface. تتيح هذه الواجهة الوصول إلى لوحة الخريطة والقوائم وأشرطة الأدوات وغيرها من أجزاء تطبيق QGIS.

لتسهيل الأمر على المستخدم، تُنفَّذ العبارات التالية عند بدء وحدة التحكم (وسيكون من الممكن مستقبلًا تعيين أوامر أولية إضافية)

from qgis.core import *
import qgis.utils

إذا كنت تستخدم وحدة التحكم كثيرًا، فقد يكون من المفيد تعيين اختصار لفتحها (من Settings ► Keyboard shortcuts...)

1.2. إضافات Python

يمكن توسيع وظائف QGIS باستخدام الإضافات، ويمكن كتابة الإضافات بلغة Python. وميزتها الرئيسية مقارنةً بإضافات C++ هي سهولة التوزيع (دون حاجة إلى الترجمة البرمجية لكل منصة) وسهولة التطوير.

كُتبت إضافات كثيرة تغطي وظائف متنوعة منذ إدخال دعم Python. ويتيح مثبّت الإضافات للمستخدمين جلب إضافات Python وتحديثها وإزالتها بسهولة. راجع صفحة إضافات Python لمزيد من المعلومات حول الإضافات وتطويرها.

إنشاء الإضافات بلغة Python أمر بسيط، راجع تطوير إضافات Python للتعليمات المفصّلة.

ملاحظة

تتوفر إضافات Python أيضًا لخادم QGIS. راجع خادم QGIS ولغة Python لمزيد من التفاصيل.

1.2.1. إضافات المعالجة

يمكن استخدام إضافات المعالجة لمعالجة البيانات. وهي أسهل تطويرًا وأكثر تخصصًا وأخف من إضافات Python. يشرح كتابة إضافة معالجة (Processing) متى يكون استخدام خوارزميات المعالجة مناسبًا وكيفية تطويرها.

1.3. تشغيل شيفرة Python عند بدء QGIS

توجد طرق مختلفة لتشغيل شيفرة Python في كل مرة يبدأ فيها QGIS.

1. إنشاء سكربت startup.py

2. تعيين متغير البيئة PYQGIS_STARTUP إلى ملف Python موجود

3. تحديد سكربت بدء باستخدام المعامل --code init_qgis.py.

1.3.1. الملف startup.py

في كل مرة يبدأ فيها QGIS، يُبحث في مجلد Python الرئيسي الخاص بالمستخدم وفي قائمة من مسارات النظام عن ملف باسم startup.py. فإن وُجد هذا الملف، نفّذه مفسّر Python المضمّن.

يوجد المسار في المجلد الرئيسي للمستخدم عادةً في:

• Linux: .local/share/QGIS/QGIS3

• Windows: AppData\Roaming\QGIS\QGIS3

• macOS: Library/Application Support/QGIS/QGIS3

تعتمد مسارات النظام الافتراضية على نظام التشغيل. لمعرفة المسارات المناسبة لك، افتح وحدة تحكم Python وشغّل QStandardPaths.standardLocations(QStandardPaths.AppDataLocation) لعرض قائمة المجلدات الافتراضية.

يُنفَّذ السكربت startup.py فور تهيئة Python في QGIS، في مرحلة مبكرة من بدء التطبيق.

1.3.2. متغير البيئة PYQGIS_STARTUP

يمكنك تشغيل شيفرة Python قبيل اكتمال تهيئة QGIS بتعيين متغير البيئة PYQGIS_STARTUP إلى مسار ملف Python موجود.

ستعمل هذه الشيفرة قبل اكتمال تهيئة QGIS. وهذه الطريقة مفيدة جدًا لتنظيف sys.path الذي قد يحتوي على مسارات غير مرغوبة، أو لعزل البيئة الأولية أو تحميلها دون الحاجة إلى بيئة افتراضية، كما في تثبيتات homebrew أو MacPorts على Mac.

1.3.3. المعامل --code

يمكنك تمرير شيفرة مخصّصة لتُنفَّذ كمعامل بدء لـ QGIS. للقيام بذلك، أنشئ ملف Python، مثل qgis_init.py، ثم ابدأ QGIS من سطر الأوامر باستخدام qgis --code qgis_init.py.

تُنفَّذ الشيفرة المُمرَّرة عبر --code في مرحلة متأخرة من تهيئة QGIS، بعد تحميل مكونات التطبيق.

1.3.4. وسائط إضافية لـ Python

لتمرير وسائط إضافية إلى سكربت --code أو إلى أي شيفرة Python أخرى تُنفَّذ، يمكنك استخدام الوسيط --py-args. أي وسيط يأتي بعد --py-args وقبل الوسيط -- (إن وُجد) يُمرَّر إلى Python ويتجاهله تطبيق QGIS نفسه.

في المثال التالي، سيكون myfile.tif متاحًا عبر sys.argv في Python لكن QGIS لن يحمّله. أما otherfile.tif فسيحمّله QGIS لكنه لن يكون موجودًا في sys.argv.

qgis --code qgis_init.py --py-args myfile.tif -- otherfile.tif

إذا أردت الوصول إلى كل معاملات سطر الأوامر من داخل Python، يمكنك استخدام QCoreApplication.arguments()

QgsApplication.instance().arguments()

1.4. تطبيقات Python

كثيرًا ما يكون من المفيد إنشاء سكربتات لأتمتة العمليات. وهذا ممكن تمامًا مع PyQGIS --- استورد الوحدة qgis.core وهيّئها، وتكون جاهزًا للمعالجة.

أو قد ترغب في إنشاء تطبيق تفاعلي يستخدم وظائف GIS --- كإجراء القياسات، وتصدير خريطة بصيغة PDF، ... توفّر الوحدة qgis.gui مكونات واجهة رسومية متنوعة، أبرزها عنصر واجهة لوحة الخريطة الذي يمكن دمجه في التطبيق مع دعم التكبير والتحريك و/أو أي أدوات خريطة مخصّصة أخرى.

يجب إعداد تطبيقات PyQGIS المخصّصة والسكربتات المستقلة لتحديد موقع موارد QGIS، مثل معلومات الإسقاط ومزوّدي البيانات لقراءة الطبقات المتجهية والشبكية. تُهيَّأ موارد QGIS بإضافة بضعة أسطر في بداية التطبيق أو السكربت. وشيفرة تهيئة QGIS متشابهة في التطبيقات المخصّصة والسكربتات المستقلة، وفيما يلي أمثلة على كلٍّ منهما.

ملاحظة

لا تستخدم qgis.py اسمًا لسكربتك، إذ لن تتمكن Python من استيراد الروابط لأن اسم السكربت سيحجبها.

1.4.1. استخدام PyQGIS في السكربتات المستقلة

لبدء سكربت مستقل، هيّئ موارد QGIS في بداية السكربت:

from qgis.core import *

# Supply path to qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.  Setting the
# second argument to False disables the GUI.
qgs = QgsApplication([], False)

# Load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

نستورد أولًا الوحدة qgis.core ونضبط مسار البادئة (prefix path). مسار البادئة هو الموقع الذي ثُبّت فيه QGIS على نظامك، ويُضبط في السكربت باستدعاء الدالة setPrefixPath(). ويُعيَّن الوسيط الثاني للدالة setPrefixPath() إلى True، للدلالة على استخدام المسارات الافتراضية.

يختلف مسار تثبيت QGIS باختلاف المنصة؛ وأسهل طريقة لمعرفته على نظامك هي استخدام كتابة السكربتات في وحدة تحكم Python من داخل QGIS والنظر إلى ناتج تشغيل:

QgsApplication.prefixPath()

بعد ضبط مسار البادئة، نحفظ مرجعًا إلى QgsApplication في المتغير qgs. ويُعيَّن الوسيط الثاني إلى False للدلالة على أننا لا ننوي استخدام الواجهة الرسومية لأننا نكتب سكربتًا مستقلًا. وبعد إعداد QgsApplication نحمّل مزوّدي بيانات QGIS وسجل الطبقات باستدعاء الدالة initQgis().

qgs.initQgis()

بعد تهيئة QGIS نكون جاهزين لكتابة بقية السكربت. وفي النهاية نختم باستدعاء exitQgis() لإزالة مزوّدي البيانات وسجل الطبقات من الذاكرة.

qgs.exitQgis()

1.4.2. استخدام PyQGIS في التطبيقات المخصّصة

الفرق الوحيد بين استخدام PyQGIS في السكربتات المستقلة وتطبيق PyQGIS مخصّص هو الوسيط الثاني عند إنشاء نسخة من QgsApplication. مرّر True بدلًا من False للدلالة على أننا ننوي استخدام واجهة رسومية.

from qgis.core import *

# Supply the path to the qgis install location
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# Create a reference to the QgsApplication.
# Setting the second argument to True enables the GUI.  We need
# this since this is a custom application.

qgs = QgsApplication([], True)

# load providers
qgs.initQgis()

# Write your code here to load some layers, use processing
# algorithms, etc.

# Finally, exitQgis() is called to remove the
# provider and layer registries from memory
qgs.exitQgis()

يمكنك الآن العمل مع QGIS API - تحميل الطبقات وإجراء بعض المعالجة أو تشغيل واجهة رسومية تحتوي لوحة خريطة. الإمكانيات لا حصر لها :-)

1.4.3. تشغيل التطبيقات المخصّصة

عليك أن تخبر نظامك بمكان البحث عن مكتبات QGIS ووحدات Python المناسبة إن لم تكن في موقع معروف - وإلا فستعترض Python:

>>> import qgis.core
ImportError: No module named qgis.core

يمكن حل ذلك بتعيين متغير البيئة PYTHONPATH. في الأوامر التالية، استبدل <qgispath> بمسار تثبيت QGIS الفعلي لديك:

• على Linux: export PYTHONPATH=/<qgispath>/share/qgis/python

• على Windows: set PYTHONPATH=c:\<qgispath>\python

• على macOS: export PYTHONPATH=/<qgispath>/Contents/Resources/python

أصبح مسار وحدات PyQGIS معروفًا الآن، لكنها تعتمد على المكتبتين qgis_core و qgis_gui (فوحدات Python ليست سوى أغلفة لهما). وقد يكون مسار هاتين المكتبتين غير معروف لنظام التشغيل، فتحصل على خطأ استيراد مجددًا (قد تختلف الرسالة باختلاف النظام):

>>> import qgis.core
ImportError: libqgis_core.so.3.2.0: cannot open shared object file:
  No such file or directory

يمكنك حل ذلك بإضافة المجلدات التي توجد فيها مكتبات QGIS إلى مسار البحث الخاص بالرابط الديناميكي (dynamic linker):

• على Linux: export LD_LIBRARY_PATH=/<qgispath>/lib

• على Windows: set PATH=C:\<qgispath>\bin;C:\<qgispath>\apps\<qgisrelease>\bin;%PATH% حيث يجب استبدال <qgisrelease> بنوع الإصدار الذي تستهدفه (مثل qgis-ltr أو qgis أو qgis-dev)

يمكن وضع هذه الأوامر في سكربت إقلاع يتولى عملية البدء. وعند نشر تطبيقات مخصّصة تستخدم PyQGIS، هناك عادةً احتمالان:

• مطالبة المستخدم بتثبيت QGIS قبل تثبيت تطبيقك. يجب أن يبحث مثبّت التطبيق في المواقع الافتراضية لمكتبات QGIS وأن يتيح للمستخدم تعيين المسار إن لم يُعثر عليها. ميزة هذا النهج أنه أبسط، لكنه يتطلب من المستخدم خطوات أكثر.

• حزم QGIS مع تطبيقك. قد يكون إصدار التطبيق أصعب وسيكون حجم الحزمة أكبر، لكن المستخدم سيُعفى من عناء تنزيل برمجيات إضافية وتثبيتها.

يمكن الجمع بين نموذجي النشر. إذ يمكنك تقديم تطبيقات مستقلة على Windows و macOS، وترك تثبيت GIS على Linux للمستخدم ومدير الحزم لديه.

1.5. ملاحظات تقنية حول PyQt و SIP

اخترنا Python لأنها من أكثر اللغات تفضيلًا لكتابة السكربتات. تعتمد روابط PyQGIS في QGIS 3 على SIP و PyQt5. والسبب في استخدام SIP بدلًا من SWIG الأوسع انتشارًا هو أن شيفرة QGIS تعتمد على مكتبات Qt. وتُنجَز روابط Python لمكتبة Qt (أي PyQt) باستخدام SIP، مما يتيح تكاملًا سلسًا بين PyQGIS و PyQt.