بدء استخدام مكتبة Google Data Python

جيفري سكودر، فريق Google Data APIs
آب (أغسطس) 2007

مقدمة

لنفترض أنّك قرّرت استخدام مكتبة عميل Google Data Python لكتابة تطبيق باستخدام إحدى خدمات Google Data العديدة. اختيار ممتاز! أهدف من خلال هذا البرنامج التعليمي القصير إلى مساعدتك في البدء بسرعة في استخدام مكتبة البرامج لتطوير تطبيقك.

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

تثبيت Python

إذا كنت ستطوّر باستخدام مكتبة برامج Python، يجب أن يتوفّر لديك إصدار 2.2 أو إصدار أحدث من Python. تتضمّن العديد من أنظمة التشغيل إصدارًا من لغة Python، لذا قد تتمكّن من تخطّي خطوة التثبيت. لمعرفة إصدار Python الذي تستخدمه، شغِّل python -V في نافذة سطر الأوامر. (يُرجى العلم أنّ V مكتوبة بأحرف كبيرة). من المفترض أن يؤدي ذلك إلى ظهور ما يلي:

Python 2.4.3

إذا ظهر لك الإصدار 2.2 أو إصدار أحدث، يمكنك البدء في تثبيت التبعيات. بخلاف ذلك، اطّلِع على التعليمات أدناه للعثور على تعليمات التثبيت/الترقية الخاصة بنظام التشغيل.

تثبيت Python على نظام التشغيل Windows

هناك العديد من عمليات تنفيذ Python التي يمكنك الاختيار من بينها في Windows، ولكن لأغراض هذا الدليل، سأستخدم أداة التثبيت ‎ .msi المتوفّرة على python.org.

  1. ابدأ بتنزيل أداة التثبيت من صفحة تنزيل Python.
  2. شغِّل أداة التثبيت، ويمكنك قبول جميع الإعدادات التلقائية.
  3. لمعرفة ما إذا كان التثبيت يعمل على النحو المتوقّع، افتح موجّه الأوامر ونفِّذ python -V.

تثبيت Python على نظام التشغيل Mac OS X

تتضمّن قائمة عمليات التنزيل على python.org برامج تثبيت بتنسيق ‎ .dmg لمستخدمي أجهزة Mac. في ما يلي خطوات تثبيت أحدها:

  1. انتقِل إلى http://www.python.org/download/mac/
  2. من هذه الصفحة، نزِّل أداة التثبيت للإصدار المناسب من نظام التشغيل Mac OS X. ملاحظة: تختلف صفحة تثبيت Python لنظام التشغيل Mac OS X 10.3.8 والإصدارات الأقدم عن الإصدارات الأحدث من نظام التشغيل Mac OS X. للعثور على إصدار OS X، اختَر لمحة عن هذا الكمبيوتر Mac من قائمة Apple في الزاوية العلوية اليسرى من الشاشة.
  3. بعد انتهاء عملية التنزيل، انقر نقرًا مزدوجًا على ملف صورة القرص الجديد (مثل python-2.5-macosx.dmg) لتثبيته. إذا كنت تستخدم متصفّح Safari، تمّ إجراء ذلك نيابةً عنك.
  4. افتح الصورة المحمَّلة وانقر مرّتين على حزمة أداة التثبيت بداخلها.
  5. اتّبِع تعليمات التثبيت واقرأ المعلومات واتفاقيات الترخيص كما تظهر لك. مرة أخرى، ستعمل الإعدادات التلقائية بشكل جيد هنا.
  6. تحقَّق من عملية التثبيت من خلال فتح Terminal.app (في /Applications/Utilities) وتشغيل python -V. من المفترض أن يظهر إصدار التثبيت.

تثبيت Python على نظام التشغيل Linux

للتثبيت على نظام التشغيل Linux وأنظمة التشغيل الأخرى التي تتضمّن *nix، أفضّل تنزيل رمز المصدر وتجميعه. ومع ذلك، قد تتمكّن من استخدام مدير الحِزم المفضّل لديك لتثبيت Python. (على سبيل المثال، على Ubuntu، يمكن إجراء ذلك بسهولة من خلال تشغيل sudo apt-get install python على سطر الأوامر). لتثبيت التطبيق من المصدر، اتّبِع الخطوات التالية:

  1. نزِّل حزمة tarball الخاصة برمز المصدر من صفحة تنزيل Python.
  2. بعد تنزيل الحزمة، فكّ ضغطها باستخدام سطر الأوامر. يمكنك استخدام ما يلي: 
    tar zxvf Python-2.<Your version>.tgz
  3. بعد ذلك، عليك تجميع رمز المصدر لمترجم Python وتثبيته. في الدليل الذي تم فك ضغطه، شغِّل ./configure لإنشاء ملف makefile.
  4. بعد ذلك، شغِّل الأمر make. سيؤدي ذلك إلى إنشاء ملف Python تنفيذي في الدليل المحلي. إذا لم يكن لديك إذن الوصول إلى الجذر أو إذا كنت تريد فقط استخدام Python من الدليل الرئيسي، يمكنك التوقف هنا. ستتمكّن من تشغيل Python من هذا الدليل، لذا قد تحتاج إلى إضافته إلى متغير بيئة PATH.
  5. أفضّل تثبيت Python في /usr/bin/ حيث تبحث معظم نصوص Python البرمجية عن المترجم. إذا كان لديك إذن وصول إلى الجذر، شغِّل make install كجذر. سيؤدي ذلك إلى تثبيت Python في الموقع التلقائي وسيكون متاحًا للاستخدام من قِبل جميع المستخدمين على جهازك.
  6. تحقَّق مما إذا كان التثبيت يعمل على النحو المتوقّع من خلال فتح نافذة طرفية وتشغيل python -V.

تثبيت الحِزم التابعة

في الوقت الحالي، لا توجد سوى تبعية خارجية واحدة، وهي مكتبة XML باسم ElementTree. إذا كنت تستخدم الإصدار 2.5 من Python أو إصدارًا أحدث، لن تحتاج إلى تثبيت ElementTree لأنّه يأتي مع حزمة Python.

للتأكّد مما إذا كانت مكتبة ElementTree متوفّرة على نظامك، اتّبِع الخطوات التالية:

  1. شغِّل مترجم Python. أفعل ذلك عادةً من خلال تنفيذ python في سطر الأوامر.
  2. جرِّب استيراد وحدة ElementTree. إذا كنت تستخدم الإصدار 2.5 أو إصدارًا أحدث من Python، أدخِل ما يلي في المترجم: 
    from xml.etree import ElementTree
     في الإصدارات القديمة، أدخِل: 
    from elementtree import ElementTree
  3. إذا تعذّر الاستيراد، عليك مواصلة قراءة هذا القسم. إذا نجحت العملية، يمكنك الانتقال إلى تثبيت مكتبة Google Data.
  4. نزِّل إصدارًا مناسبًا لنظام التشغيل. على سبيل المثال، إذا كنت تستخدم نظام التشغيل Windows، نزِّل elementtree-1.2.6-20050316.win32.exe. بالنسبة إلى أنظمة التشغيل الأخرى، أنصحك بتنزيل نسخة مضغوطة.
  5. إذا كنت تستخدم إصدار .tar.gz أو .zip من المكتبة، عليك أولاً فك الحزمة، ثم تثبيتها عن طريق تشغيل ./setup.py install.

يؤدي تنفيذ ./setup.py install إلى محاولة تجميع المكتبة ووضعها في دليل النظام لوحدات Python. إذا لم يكن لديك إذن الوصول إلى الجذر، يمكنك تثبيت الوحدات في الدليل الرئيسي أو في موقع جغرافي بديل عن طريق تشغيل ./setup.py install --home=~. سيؤدي ذلك إلى وضع الرمز في دليل المنزل.

يتوفّر خيار آخر لتجنُّب التثبيت تمامًا. بعد فك ضغط الملف الذي تم تنزيله، ستجد مجلدًا باسم elementtree. يحتوي هذا الدليل على الوحدات التي ستحتاج إلى استيرادها. عند استيراد وحدة من داخل Python، يبحث عن وحدة بالاسم المطلوب في عدة أماكن. يبحث البرنامج أولاً في الدليل الحالي، لذا إذا كنت تنفّذ التعليمات البرمجية دائمًا من دليل واحد، يمكنك وضع دليل elementtree هناك. ستبحث بايثون أيضًا في الدلائل المدرَجة في متغيّر البيئة PYTHONPATH. للحصول على تعليمات حول تعديل PYTHONPATH، يُرجى الاطّلاع على الملحق في نهاية هذه المقالة. أنصحك باستخدام ./setup.py install في elementtree.

تثبيت مكتبة Google Data

نزِّل مكتبة Google Data Python إذا لم يسبق لك ذلك. ابحث عن أحدث إصدار في صفحة التنزيلات الخاصة بمشروع Python.

بعد تنزيل المكتبة، فكّ ضغطها باستخدام unzip أو tar zxvf استنادًا إلى نوع التنزيل الذي اخترته.

أنت الآن جاهز لتثبيت وحدات المكتبة حتى يمكن استيرادها إلى Python. وتتعدّد طرق تأكيد ذلك:

  • إذا كان بإمكانك تثبيت حِزم ليتمكّن جميع المستخدمين من الوصول إليها، يمكنك تشغيل ./setup.py install من الدليل الرئيسي للأرشيف الذي تم فك ضغطه.
  • إذا أردت تثبيت هذه الوحدات لاستخدامها في دليل المنزل، يمكنك تشغيل ./setup.py install --home=<your home directory>.

  • في بعض الحالات، قد تريد تجنُّب تثبيت الوحدات تمامًا. لإجراء ذلك، عدِّل متغيّر البيئة PYTHONPATH ليشمل دليلاً يحتوي على الدليلَين gdata وatom الخاصَين بمكتبة برامج Google Data Python. للحصول على تعليمات حول تعديل PYTHONPATH، يُرجى الاطّلاع على الملحق في نهاية هذه المقالة.

  • أودّ أن أذكر خيارًا أخيرًا، وهو نسخ الدليلَين gdata وatom من الدليل src إلى أي دليل آخر تكون فيه عند تنفيذ الأمر python. ستبحث لغة Python في الدليل الحالي عند إجراء عملية استيراد، ولكن لا أنصحك بهذه الطريقة إلا إذا كنت تريد إنشاء شيء سريع وبسيط.

بعد تثبيت مكتبة "بيانات Google"، ستكون جاهزًا لتجربتها.

إجراء الاختبارات وأخذ العيّنات

تتضمّن توزيعات مكتبة برامج Google Data Python بعض حالات الاختبار التي يتم استخدامها في تطوير المكتبة. ويمكن أن تكون أيضًا بمثابة فحص سريع للتأكّد من أنّ التبعيات وعملية تثبيت المكتبة تعملان بشكل سليم. من دليل المستوى الأعلى الذي فككت فيه نسخة المكتبة، جرِّب تنفيذ ما يلي:

./tests/run_data_tests.py

إذا تم تشغيل هذا النص البرمجي بشكل صحيح، من المفترَض أن تظهر لك النتائج التالية على سطر الأوامر:

Running all tests in module gdata_test
.......
----------------------------------------------------------------------
Ran 7 tests in 0.025s

OK

Running all tests in module atom_test
..........................................
----------------------------------------------------------------------
Ran 42 tests in 0.016s

OK

...

إذا لم تظهر لك أي أخطاء أثناء تنفيذ الاختبارات، من المحتمل أنّك أعددت بيئتك بشكلٍ صحيح. تهانينا!

يمكنك الآن بدء تشغيل شيء أكثر إثارة للاهتمام. يحتوي التوزيع على دليل samples يتضمّن رمزًا برمجيًا يمكن أن يوفّر نقطة بداية لكتابة تطبيقك. إذا أردت تجربة نموذج تفاعلي بسيط، جرِّب تشغيل ./samples/docs/docs_example.py. سيطلب منك نموذج Google Documents List API إدخال عنوان البريد الإلكتروني وكلمة المرور لحسابك على Google. إذا كان لديك أي مستندات أو جداول بيانات في مستندات Google، يمكنك إدراجها عن طريق إدخال 1 للعملية التي اخترتها. (إذا لم يكن لديك أي مستندات أو جداول بيانات، سيظهر لك الخطأ 404).

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

كتابة مثال "Hello World"

لنبدأ بمثال بسيط. في ما يلي برنامج قصير لطباعة قائمة بجميع المستندات في حسابك على مستندات Google:

import gdata.docs.service

# Create a client class which will make HTTP requests with Google Docs server.
client = gdata.docs.service.DocsService()
# Authenticate using your Google Docs email address and password.
client.ClientLogin('jo@gmail.com', 'password')

# Query the server for an Atom feed containing a list of your documents.
documents_feed = client.GetDocumentListFeed()
# Loop through the feed and extract each document entry.
for document_entry in documents_feed.entry:
  # Display the title of the document on the command line.
  print document_entry.title.text

يمكنك حفظ مقتطف الرمز البرمجي أعلاه كملف وتشغيله، أو لصق الرمز في مفسّر Python للاطّلاع على مكتبة برامج Google Data Python تعمل.

الخاتمة

بعد تثبيت مكتبة برامج Google Data Python واختبارها، يمكنك البدء في كتابة التطبيق الرائع التالي باستخدام:

أثناء مواصلة تطوير تطبيقك، قد تواجه مشكلة. إذا كان الأمر كذلك، يُرجى الاطّلاع على قائمة المراجع أدناه:

إذا خطرت لك فكرة رائعة بشأن ميزة جديدة للمكتبة (أو إذا عثرت على خطأ)، يُرجى إدخالها في مجموعة المناقشة. نحن مهتمّون دائمًا بمعرفة ملاحظاتك.

مع أطيب التحيّات :-)

الملحق: تعديل PYTHONPATH

عند استيراد حزمة أو وحدة في Python، يبحث المترجم عن الملف في سلسلة من المواقع، بما في ذلك جميع الأدلة المدرَجة في متغير البيئة PYTHONPATH. أعدّل غالبًا PYTHONPATH للإشارة إلى الوحدات التي نسخت فيها رمز المصدر لمكتبة أستخدمها. يؤدي ذلك إلى تجنُّب الحاجة إلى تثبيت وحدة في كل مرة يتم تعديلها، لأنّ Python سيحمّل الوحدة مباشرةً من الدليل الذي يحتوي على رمز المصدر المعدَّل.

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

عدّلتُ PYTHONPATH على نظام *nix وMac OS X من خلال ضبطه في ملف إعداد shell الخاص بـ .bashrc. إذا كنت تستخدم shell bash، يمكنك ضبط المتغيّر من خلال إضافة السطر التالي إلى ملف ~/.bashrc.

export PYTHONPATH=$PYTHONPATH:/home/<my_username>/svn/gdata-python-client/src

يمكنك بعد ذلك تطبيق هذه التغييرات على جلسة shell الحالية من خلال تنفيذ source ~/.bashrc.

في نظام التشغيل Windows XP، اعرض "متغيرات البيئة" لملفك الشخصي: لوحة التحكّم > خصائص النظام > خيارات متقدّمة > متغيرات البيئة. بعد ذلك، يمكنك إنشاء المتغيّر PYTHONPATH أو تعديله وإضافة موقع نسخة المكتبة المحلية.